Registry

npm install @hareru/registry

import { loadRegistry } from '@hareru/registry';
import type { ComponentRegistryJSON } from '@hareru/registry';

const registry: ComponentRegistryJSON = loadRegistry();

console.log(registry.name);           // "hareru-ui"
console.log(registry.componentCount); // 60
console.log(registry.components[0]);  // ComponentEntry
console.log(registry.taskBundles);    // TaskBundle[] | undefined

import { loadTokens } from '@hareru/registry';
import type { TokensJSON } from '@hareru/registry';

const tokens: TokensJSON = loadTokens();

console.log(Object.keys(tokens.light)); // array of CSS variable names
console.log(Object.keys(tokens.dark));  // dark theme overrides

import { loadSchema } from '@hareru/registry';
import type { SchemaJSON } from '@hareru/registry';

const schema: SchemaJSON = loadSchema();

// valid CSS variable names
const cssVars = schema.properties.cssVariables.items.enum;
// type constraints (pattern matching)
const constraints = schema.properties.typeConstraints.properties;

import { loadComponentSchema } from '@hareru/registry';
import type { ComponentSchemaJSON } from '@hareru/registry';

const schema: ComponentSchemaJSON = loadComponentSchema();

import { loadConsumerRules } from '@hareru/registry';
import type { ConsumerRulesJSON } from '@hareru/registry';

const rules: ConsumerRulesJSON = loadConsumerRules();

console.log(rules.version);
console.log(Object.keys(rules.rules));  // rule categories
console.log(rules.tokenQuickReference); // token quick reference

interface ComponentEntry {
  name: string;                        // "Button"
  displayName: string;                 // "Button"
  group: ComponentGroup;               // "core" | "form" | "layout" | ...
  cssArtifact: string;                 // "@hareru/ui/button.css"
  requiredCssArtifacts: string[];      // CSS artifacts this component depends on
  tokenCategories: TokenCategory[];    // token categories used
  subcomponents?: string[];            // subcomponent names
  variants?: VariantDef[];             // CVA variant definitions
  props?: PropDef[];                   // prop definitions
  states?: StateDef[];                 // state definitions (boolean / enum)
  a11y?: A11yDef;                      // accessibility definition
  slots?: SlotDef[];                   // slot structure (compound components)
  examples?: ExampleDef[];             // usage examples
  componentSource: string;             // source file path
  description: string;                 // component description
  aiHint?: string;                     // hint for AI agents
  peerComponents?: string[];           // related components
}

type StateDef = StateBooleanDef | StateEnumDef;

interface StateBooleanDef {
  name: string;                          // "disabled"
  type: 'boolean';
  cssReflection?: 'modifier' | 'data-attribute';
}

interface StateEnumDef {
  name: string;                          // "variant"
  type: 'enum';
  values: string[];                      // ["default", "destructive", "outline"]
  defaultValue?: string;                 // "default"
  cssReflection?: 'modifier' | 'data-attribute';
}

interface A11yDef {
  roles?: string[];                // WAI-ARIA roles
  ariaAttributes?: string[];       // ARIA attributes used
  semanticElements?: string[];     // recommended HTML elements
  keyboardInteractions?: string[]; // keyboard interactions
  liveRegion?: boolean;            // whether this is a live region
  notes?: string;                  // additional notes
}

interface SlotDef {
  name: string;        // "DialogContent"
  role: SlotRole;      // "content"
  parent: string;      // "Dialog" (root component name = direct child)
  expected: boolean;   // recommended in canonical composition (not runtime-required)
  multiple: boolean;   // whether multiple instances are allowed under the same parent
}

type SlotRole =
  | 'trigger' | 'content' | 'container' | 'item'
  | 'label' | 'description' | 'action' | 'separator'
  | 'indicator' | 'viewport' | 'close' | 'icon'
  | 'input' | 'submenu' | 'anchor' | 'control';

interface CssModeContext {
  hasTailwind: boolean;        // whether Tailwind CSS is detected
  componentCount: number;      // number of Hareru components in use
  hasExistingReset?: boolean;  // whether an existing CSS reset or framework is present
}

import { recommendCssMode, CSS_MODES, CSS_MODE_DESCRIPTIONS } from '@hareru/registry';

const { mode, reason } = recommendCssMode({
  hasTailwind: true,
  componentCount: 10,
});

console.log(mode);   // "tailwind"
console.log(reason); // "Tailwind CSS detected. Uses Cascade Layers..."

// all valid CSS modes
CSS_MODES: readonly CssMode[]
// => ['standalone', 'portable', 'tailwind', 'per-component']

// description for each mode
CSS_MODE_DESCRIPTIONS: Readonly<Record<CssMode, string>>

import { buildSlotTree } from '@hareru/registry';
import type { SlotDef } from '@hareru/registry';

const slots: SlotDef[] = [
  { name: 'DialogTrigger', role: 'trigger', parent: 'Dialog', expected: true, multiple: false },
  { name: 'DialogContent', role: 'content', parent: 'Dialog', expected: true, multiple: false },
  { name: 'DialogHeader',  role: 'container', parent: 'DialogContent', expected: false, multiple: false },
  { name: 'DialogClose',   role: 'close', parent: 'DialogContent', expected: false, multiple: false },
];

const tree = buildSlotTree('Dialog', slots);
console.log(tree);

Dialog
├── DialogTrigger [trigger] (expected)
└── DialogContent [content] (expected)
    ├── DialogHeader [container]
    └── DialogClose [close]

(expected) = recommended in canonical composition, not runtime-required.

const tree = buildSlotTree('Table', slots, [
  'TableRow is also valid inside TableHeader.',
]);