@ankhorage/zora 1.2.0 → 1.4.0

package/src/components/textarea/meta.ts

@@ -0,0 +1,46 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const textareaMeta = {
+  name: 'Textarea',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Textarea',
+    defaultProps: {
+      placeholder: 'Enter text…',
+      value: '',
+    },
+  },
+  props: {
+    placeholder: {
+      type: 'string',
+      category: 'Content',
+      label: 'Placeholder',
+    },
+    value: {
+      type: 'string',
+      category: 'Content',
+      label: 'Value',
+      default: '',
+    },
+    size: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Size',
+      enum: ['s', 'm', 'l'],
+    },
+    disabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Disabled',
+      default: false,
+    },
+    readOnly: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Read-only',
+      default: false,
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/components/toolbar/meta.ts

@@ -0,0 +1,19 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const toolbarMeta = {
+  name: 'Toolbar',
+  category: 'component',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Action bar component; not represented as a manifest node in v1.',
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const toolbarActionMeta = {
+  name: 'ToolbarAction',
+  category: 'component',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Action bar item; not represented as a manifest node in v1.',
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/foundation/meta.ts

@@ -0,0 +1,85 @@
+import type { ZoraComponentMetaRegistry } from '../metadata';
+import { CONTAINER_ALLOWED_CHILDREN } from '../metadata/allowedChildren';
+
+export const foundationMetas = {
+  Box: {
+    name: 'Box',
+    category: 'foundation',
+    directManifestNode: true,
+    allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+    blueprint: { label: 'Box' },
+    props: {},
+  },
+  Center: {
+    name: 'Center',
+    category: 'foundation',
+    directManifestNode: false,
+    allowedChildren: [],
+    note: 'Layout helper component; not represented as a manifest node in v1.',
+    props: {},
+  },
+  Container: {
+    name: 'Container',
+    category: 'foundation',
+    directManifestNode: true,
+    allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+    blueprint: { label: 'Container' },
+    props: {},
+  },
+  Divider: {
+    name: 'Divider',
+    category: 'foundation',
+    directManifestNode: true,
+    allowedChildren: [],
+    blueprint: { label: 'Divider' },
+    props: {},
+  },
+  Grid: {
+    name: 'Grid',
+    category: 'foundation',
+    directManifestNode: true,
+    allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+    blueprint: { label: 'Grid' },
+    props: {},
+  },
+  Inline: {
+    name: 'Inline',
+    category: 'foundation',
+    directManifestNode: false,
+    allowedChildren: [],
+    note: 'Layout helper component; not represented as a manifest node in v1.',
+    props: {},
+  },
+  Show: {
+    name: 'Show',
+    category: 'foundation',
+    directManifestNode: false,
+    allowedChildren: [],
+    note: 'Responsive utility component; not represented as a manifest node in v1.',
+    props: {},
+  },
+  Spacer: {
+    name: 'Spacer',
+    category: 'foundation',
+    directManifestNode: false,
+    allowedChildren: [],
+    note: 'Spacing utility component; not represented as a manifest node in v1.',
+    props: {},
+  },
+  Stack: {
+    name: 'Stack',
+    category: 'foundation',
+    directManifestNode: true,
+    allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+    blueprint: { label: 'Stack' },
+    props: {},
+  },
+  Surface: {
+    name: 'Surface',
+    category: 'foundation',
+    directManifestNode: false,
+    allowedChildren: [],
+    note: 'Low-level surface wrapper; not represented as a manifest node in v1.',
+    props: {},
+  },
+} as const satisfies ZoraComponentMetaRegistry;

package/src/index.ts

@@ -137,6 +137,19 @@ export type { SidebarLayoutProps } from './layout/sidebar-layout';
 export { SidebarLayout } from './layout/sidebar-layout';
 export type { TopbarLayoutProps } from './layout/topbar-layout';
 export { TopbarLayout } from './layout/topbar-layout';
+export type {
+  ZoraComponentBlueprint,
+  ZoraComponentCategory,
+  ZoraComponentI18nMeta,
+  ZoraComponentMeta,
+  ZoraComponentMetaRegistry,
+  ZoraComponentPropArrayItemSchema,
+  ZoraComponentPropSchema,
+  ZoraComponentPropType,
+  ZoraComponentPropValue,
+  ZoraComponentSlotMeta,
+} from './metadata';
+export { ZORA_COMPONENT_META } from './metadata';
 export type {
   AuthFormBaseProps,
   AuthIdentifierKind,
@@ -200,6 +213,15 @@ export type {
 export { ResponsivePanel } from './patterns/responsive-panel';
 export type { SectionHeaderProps } from './patterns/section-header';
 export { SectionHeader } from './patterns/section-header';
+export type {
+  SelectableItemProps,
+  SelectableItemState,
+  SelectionMode,
+  SelectionProviderProps,
+  SelectionTrigger,
+  UseSelectionResult,
+} from './patterns/selection';
+export { SelectableItem, SelectionProvider, useSelection } from './patterns/selection';
 export type { SettingsRowProps } from './patterns/settings-row';
 export { SettingsRow } from './patterns/settings-row';
 export type { SwitchFieldProps } from './patterns/switch-field';

package/src/layout/app-shell/meta.ts

@@ -0,0 +1,10 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const appShellMeta = {
+  name: 'AppShell',
+  category: 'layout',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Application shell layout; not represented as a manifest node in v1.',
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/layout/auth-layout/meta.ts

@@ -0,0 +1,35 @@
+import type { ZoraComponentMeta } from '../../metadata';
+import { PAGE_SECTION_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+
+export const authLayoutMeta = {
+  name: 'AuthLayout',
+  category: 'layout',
+  directManifestNode: true,
+  allowedChildren: [...PAGE_SECTION_ALLOWED_CHILDREN],
+  blueprint: {
+    label: 'Auth layout',
+    defaultProps: {
+      title: 'Welcome',
+      description: 'Sign in to continue.',
+    },
+  },
+  props: {
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+      default: 'Welcome',
+    },
+    description: {
+      type: 'string',
+      category: 'Content',
+      label: 'Description',
+      default: 'Sign in to continue.',
+    },
+    eyebrow: {
+      type: 'string',
+      category: 'Content',
+      label: 'Eyebrow',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/layout/page/meta.ts

@@ -0,0 +1,21 @@
+import type { ZoraComponentMeta } from '../../metadata';
+import { PAGE_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+
+export const pageMeta = {
+  name: 'Page',
+  category: 'layout',
+  directManifestNode: true,
+  allowedChildren: [...PAGE_ALLOWED_CHILDREN],
+  blueprint: {
+    label: 'Page',
+  },
+  props: {
+    width: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Width',
+      enum: ['narrow', 'default', 'wide'],
+      default: 'default',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/layout/page-header/meta.ts

@@ -0,0 +1,39 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const pageHeaderMeta = {
+  name: 'PageHeader',
+  category: 'layout',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Page header',
+    defaultProps: {
+      title: 'Page title',
+      description: 'Short description.',
+    },
+  },
+  props: {
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+      default: 'Page title',
+    },
+    description: {
+      type: 'string',
+      category: 'Content',
+      label: 'Description',
+      default: 'Short description.',
+    },
+    eyebrow: {
+      type: 'string',
+      category: 'Content',
+      label: 'Eyebrow',
+    },
+    meta: {
+      type: 'string',
+      category: 'Content',
+      label: 'Meta',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/layout/page-section/meta.ts

@@ -0,0 +1,30 @@
+import type { ZoraComponentMeta } from '../../metadata';
+import { PAGE_SECTION_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+
+export const pageSectionMeta = {
+  name: 'PageSection',
+  category: 'layout',
+  directManifestNode: true,
+  allowedChildren: [...PAGE_SECTION_ALLOWED_CHILDREN],
+  blueprint: {
+    label: 'Page section',
+    defaultProps: {
+      title: 'Section',
+      description: 'Section description.',
+    },
+  },
+  props: {
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+      default: 'Section',
+    },
+    description: {
+      type: 'string',
+      category: 'Content',
+      label: 'Description',
+      default: 'Section description.',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/layout/settings-layout/meta.ts

@@ -0,0 +1,10 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const settingsLayoutMeta = {
+  name: 'SettingsLayout',
+  category: 'layout',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Application layout; not represented as a manifest node in v1.',
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/layout/sidebar-layout/meta.ts

@@ -0,0 +1,10 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const sidebarLayoutMeta = {
+  name: 'SidebarLayout',
+  category: 'layout',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Application layout; not represented as a manifest node in v1.',
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/layout/topbar-layout/meta.ts

@@ -0,0 +1,10 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const topbarLayoutMeta = {
+  name: 'TopbarLayout',
+  category: 'layout',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Application layout; not represented as a manifest node in v1.',
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/metadata/allowedChildren.ts

@@ -0,0 +1,27 @@
+export const CONTAINER_ALLOWED_CHILDREN = [
+  'Box',
+  'Stack',
+  'Grid',
+  'Container',
+  'Divider',
+  'Text',
+  'Heading',
+  'Button',
+  'Input',
+  'Textarea',
+  'FormField',
+  'Card',
+  'Panel',
+  'Notice',
+  'EmptyState',
+  'SectionHeader',
+  'SettingsRow',
+] as const;
+
+export const PAGE_SECTION_ALLOWED_CHILDREN = [...CONTAINER_ALLOWED_CHILDREN] as const;
+
+export const PAGE_ALLOWED_CHILDREN = [
+  'PageHeader',
+  'PageSection',
+  ...CONTAINER_ALLOWED_CHILDREN,
+] as const;

package/src/metadata/componentMeta.test.ts

@@ -0,0 +1,204 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+import { ZORA_COMPONENT_META } from './componentMeta';
+
+const ROOT = process.cwd();
+const SRC_ROOT = join(ROOT, 'src');
+
+const INDEX_PATH = join(SRC_ROOT, 'index.ts');
+const THEME_INDEX_PATH = join(SRC_ROOT, 'theme', 'index.ts');
+
+function parseReexportBlocks(source: string): { names: string[]; from: string; isType: boolean }[] {
+  const pattern = /\bexport\s+(type\s+)?\{([\s\S]*?)\}\s*from\s*['"]([^'"]+)['"]/g;
+  const blocks: { names: string[]; from: string; isType: boolean }[] = [];
+
+  for (const match of source.matchAll(pattern)) {
+    const isType = match[1] !== undefined;
+    const rawNames = match[2] ?? '';
+    const from = match[3] ?? '';
+
+    const names = rawNames
+      .split(',')
+      .map((item) => item.trim())
+      .filter(Boolean)
+      .map((item) =>
+        item
+          .replace(/^type\s+/, '')
+          .split(/\s+as\s+/)[0]
+          ?.trim(),
+      )
+      .filter((item): item is string => Boolean(item));
+
+    blocks.push({ names, from, isType });
+  }
+
+  return blocks;
+}
+
+function readSource(filePath: string): string {
+  return readFileSync(filePath, 'utf8');
+}
+
+function isComponentExportName(name: string): boolean {
+  return /^[A-Z][A-Za-z0-9]*$/.test(name);
+}
+
+function isJsonSerializable(value: unknown): boolean {
+  if (value === null) return true;
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+    return true;
+  if (Array.isArray(value)) return value.every((item) => isJsonSerializable(item));
+  if (typeof value !== 'object') return false;
+
+  const record = value as Record<string, unknown>;
+  return Object.values(record).every((item) => isJsonSerializable(item));
+}
+
+describe('ZORA_COMPONENT_META public API', () => {
+  test('src/index.ts re-exports ZORA_COMPONENT_META', () => {
+    const indexSource = readSource(INDEX_PATH);
+    expect(indexSource).toContain('ZORA_COMPONENT_META');
+  });
+});
+
+describe('ZORA_COMPONENT_META registry coverage', () => {
+  test('covers every public UI React component export (foundation/components/patterns/layout)', () => {
+    // Avoid importing the full src/index.ts barrel here; Bun has been observed to crash when executing
+    // module graphs that touch react-native. We do drift checks via static source parsing instead.
+    const indexSource = readSource(INDEX_PATH);
+    const blocks = parseReexportBlocks(indexSource).filter((block) => !block.isType);
+
+    const uiComponentNames = new Set(
+      blocks
+        .filter((block) => {
+          return (
+            block.from.startsWith('./foundation') ||
+            block.from.startsWith('./components') ||
+            block.from.startsWith('./patterns') ||
+            block.from.startsWith('./layout')
+          );
+        })
+        .flatMap((block) => block.names)
+        .filter(isComponentExportName),
+    );
+
+    const registryKeys = new Set(Object.keys(ZORA_COMPONENT_META));
+    expect([...uiComponentNames].sort()).toEqual([...registryKeys].sort());
+  });
+
+  test('does not treat providers/scopes as UI component registry entries', () => {
+    const indexSource = readSource(INDEX_PATH);
+    expect(indexSource).toContain("export * from './theme';");
+
+    const themeSource = readSource(THEME_INDEX_PATH);
+    const themeBlocks = parseReexportBlocks(themeSource).filter((block) => !block.isType);
+    const themeValueExports = new Set(
+      themeBlocks.flatMap((block) => block.names).filter(isComponentExportName),
+    );
+
+    const providerExports = new Set(['ZoraProvider', 'ZoraThemeScope']);
+
+    for (const providerExport of providerExports) {
+      expect(themeValueExports.has(providerExport)).toBe(true);
+      expect(Object.prototype.hasOwnProperty.call(ZORA_COMPONENT_META, providerExport)).toBe(false);
+    }
+  });
+});
+
+describe('ZORA_COMPONENT_META invariants', () => {
+  test('every key matches meta.name', () => {
+    for (const [key, meta] of Object.entries(ZORA_COMPONENT_META)) {
+      expect(meta.name).toBe(key);
+    }
+  });
+
+  test('allowedChildren always points to a known direct manifest node', () => {
+    for (const [key, meta] of Object.entries(ZORA_COMPONENT_META)) {
+      for (const child of meta.allowedChildren) {
+        const childMeta = ZORA_COMPONENT_META[child];
+        expect(childMeta, `${key} allowedChildren includes unknown key '${child}'`).toBeDefined();
+        expect(
+          childMeta.directManifestNode,
+          `${key} allowedChildren includes non-directManifestNode key '${child}'`,
+        ).toBe(true);
+      }
+    }
+  });
+
+  test('direct manifest node leaf/container rules', () => {
+    const expectedLeafNodes = new Set([
+      'PageHeader',
+      'SectionHeader',
+      'SettingsRow',
+      'EmptyState',
+      'Button',
+      'Input',
+      'Textarea',
+      'Text',
+      'Heading',
+      'Divider',
+    ]);
+
+    const expectedContainerNodes = new Set([
+      'FormField',
+      'Page',
+      'PageSection',
+      'AuthLayout',
+      'Card',
+      'Panel',
+      'Notice',
+      'Box',
+      'Stack',
+      'Grid',
+      'Container',
+    ]);
+
+    for (const [key, meta] of Object.entries(ZORA_COMPONENT_META)) {
+      if (!meta.directManifestNode) continue;
+
+      if (expectedLeafNodes.has(key)) {
+        expect(meta.allowedChildren.length, `${key} should be a leaf manifest node`).toBe(0);
+        continue;
+      }
+
+      if (expectedContainerNodes.has(key)) {
+        expect(
+          meta.allowedChildren.length,
+          `${key} should be a container manifest node`,
+        ).toBeGreaterThan(0);
+        continue;
+      }
+
+      throw new Error(
+        `Direct manifest node '${key}' must be categorized as leaf or container in the test.`,
+      );
+    }
+  });
+
+  test('non-direct manifest nodes include an explicit note', () => {
+    for (const [key, meta] of Object.entries(ZORA_COMPONENT_META)) {
+      if (meta.directManifestNode) continue;
+
+      expect(
+        typeof meta.note === 'string' && meta.note.trim().length > 0,
+        `${key} must include a note when directManifestNode is false`,
+      ).toBe(true);
+    }
+  });
+
+  test('registry and blueprints are JSON serializable', () => {
+    expect(() => JSON.stringify(ZORA_COMPONENT_META)).not.toThrow();
+
+    for (const [key, meta] of Object.entries(ZORA_COMPONENT_META)) {
+      if (!meta.blueprint?.defaultProps) continue;
+
+      expect(
+        isJsonSerializable(meta.blueprint.defaultProps),
+        `${key} blueprint.defaultProps contains a non-serializable value`,
+      ).toBe(true);
+    }
+  });
+});