@ankhorage/zora 1.2.0 → 1.4.0

package/src/metadata/componentMeta.ts

@@ -0,0 +1,147 @@
+import { appBarMeta } from '../components/app-bar/meta';
+import { avatarMeta } from '../components/avatar/meta';
+import { avatarGroupMeta } from '../components/avatar-group/meta';
+import { badgeMeta } from '../components/badge/meta';
+import { buttonMeta } from '../components/button/meta';
+import { cardMeta } from '../components/card/meta';
+import { checkboxGroupMeta, checkboxMeta } from '../components/checkbox/meta';
+import { chipMeta } from '../components/chip/meta';
+import { chipGroupMeta } from '../components/chip-group/meta';
+import { drawerMeta } from '../components/drawer/meta';
+import { formActionsMeta, formErrorMeta, formFieldMeta, formMeta } from '../components/form/meta';
+import { headingMeta } from '../components/heading/meta';
+import { iconMeta } from '../components/icon/meta';
+import { iconButtonMeta } from '../components/icon-button/meta';
+import { imageMeta } from '../components/image/meta';
+import { inputMeta } from '../components/input/meta';
+import { mediaCardMeta } from '../components/media-card/meta';
+import { metricCardMeta } from '../components/metric-card/meta';
+import { modalMeta } from '../components/modal/meta';
+import { navigationItemMeta } from '../components/navigation-item/meta';
+import { navigationListMeta } from '../components/navigation-list/meta';
+import { progressMeta } from '../components/progress/meta';
+import { radioGroupMeta, radioMeta } from '../components/radio/meta';
+import { ratingMeta } from '../components/rating/meta';
+import { searchBarMeta } from '../components/search-bar/meta';
+import { selectMeta } from '../components/select/meta';
+import { tabsMeta } from '../components/tabs/meta';
+import { textMeta } from '../components/text/meta';
+import { textareaMeta } from '../components/textarea/meta';
+import { toolbarActionMeta, toolbarMeta } from '../components/toolbar/meta';
+import { foundationMetas } from '../foundation/meta';
+import { appShellMeta } from '../layout/app-shell/meta';
+import { authLayoutMeta } from '../layout/auth-layout/meta';
+import { pageMeta } from '../layout/page/meta';
+import { pageHeaderMeta } from '../layout/page-header/meta';
+import { pageSectionMeta } from '../layout/page-section/meta';
+import { settingsLayoutMeta } from '../layout/settings-layout/meta';
+import { sidebarLayoutMeta } from '../layout/sidebar-layout/meta';
+import { topbarLayoutMeta } from '../layout/topbar-layout/meta';
+import {
+  forgotPasswordFormMeta,
+  otpFormMeta,
+  signInFormMeta,
+  signUpFormMeta,
+} from '../patterns/auth/meta';
+import { collectionEditorMeta } from '../patterns/collection-editor/meta';
+import { confirmDialogMeta } from '../patterns/confirm-dialog/meta';
+import { disclosureSectionMeta } from '../patterns/disclosure-section/meta';
+import { emptyStateMeta } from '../patterns/empty-state/meta';
+import { filterBarMeta } from '../patterns/filter-bar/meta';
+import { imagePreviewMeta } from '../patterns/image-preview/meta';
+import { imageUploadFieldMeta } from '../patterns/image-upload-field/meta';
+import { inspectorFieldMeta } from '../patterns/inspector-field/meta';
+import { listMeta, listRowMeta, listSectionMeta } from '../patterns/list/meta';
+import { noticeMeta } from '../patterns/notice/meta';
+import { panelMeta } from '../patterns/panel/meta';
+import { responsivePanelMeta } from '../patterns/responsive-panel/meta';
+import { sectionHeaderMeta } from '../patterns/section-header/meta';
+import { selectableItemMeta, selectionProviderMeta } from '../patterns/selection/meta';
+import { settingsRowMeta } from '../patterns/settings-row/meta';
+import { switchFieldMeta } from '../patterns/switch-field/meta';
+import { themeComposerMeta } from '../patterns/theme-composer/meta';
+import { paletteItemMeta, tileGridMeta } from '../patterns/tile-grid/meta';
+import { timelineMeta } from '../patterns/timeline/meta';
+import { treeItemMeta, treeViewMeta } from '../patterns/tree-view/meta';
+import { zoraDrawerContentMeta } from '../patterns/zora-drawer-content/meta';
+import { zoraTabBarMeta } from '../patterns/zora-tab-bar/meta';
+import type { ZoraComponentMetaRegistry } from './types';
+
+export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = {
+  ...foundationMetas,
+  AppBar: appBarMeta,
+  Avatar: avatarMeta,
+  AvatarGroup: avatarGroupMeta,
+  Badge: badgeMeta,
+  Button: buttonMeta,
+  Card: cardMeta,
+  Checkbox: checkboxMeta,
+  CheckboxGroup: checkboxGroupMeta,
+  Chip: chipMeta,
+  ChipGroup: chipGroupMeta,
+  Drawer: drawerMeta,
+  Form: formMeta,
+  FormActions: formActionsMeta,
+  FormError: formErrorMeta,
+  FormField: formFieldMeta,
+  Heading: headingMeta,
+  Icon: iconMeta,
+  IconButton: iconButtonMeta,
+  Image: imageMeta,
+  Input: inputMeta,
+  MediaCard: mediaCardMeta,
+  MetricCard: metricCardMeta,
+  Modal: modalMeta,
+  NavigationItem: navigationItemMeta,
+  NavigationList: navigationListMeta,
+  Progress: progressMeta,
+  Radio: radioMeta,
+  RadioGroup: radioGroupMeta,
+  Rating: ratingMeta,
+  SearchBar: searchBarMeta,
+  Select: selectMeta,
+  Tabs: tabsMeta,
+  Text: textMeta,
+  Textarea: textareaMeta,
+  Toolbar: toolbarMeta,
+  ToolbarAction: toolbarActionMeta,
+  AppShell: appShellMeta,
+  AuthLayout: authLayoutMeta,
+  Page: pageMeta,
+  PageHeader: pageHeaderMeta,
+  PageSection: pageSectionMeta,
+  SettingsLayout: settingsLayoutMeta,
+  SidebarLayout: sidebarLayoutMeta,
+  TopbarLayout: topbarLayoutMeta,
+  ForgotPasswordForm: forgotPasswordFormMeta,
+  OtpForm: otpFormMeta,
+  SignInForm: signInFormMeta,
+  SignUpForm: signUpFormMeta,
+  CollectionEditor: collectionEditorMeta,
+  ConfirmDialog: confirmDialogMeta,
+  DisclosureSection: disclosureSectionMeta,
+  EmptyState: emptyStateMeta,
+  FilterBar: filterBarMeta,
+  ImagePreview: imagePreviewMeta,
+  ImageUploadField: imageUploadFieldMeta,
+  InspectorField: inspectorFieldMeta,
+  List: listMeta,
+  ListRow: listRowMeta,
+  ListSection: listSectionMeta,
+  Notice: noticeMeta,
+  Panel: panelMeta,
+  ResponsivePanel: responsivePanelMeta,
+  SectionHeader: sectionHeaderMeta,
+  SelectableItem: selectableItemMeta,
+  SelectionProvider: selectionProviderMeta,
+  SettingsRow: settingsRowMeta,
+  SwitchField: switchFieldMeta,
+  ThemeComposer: themeComposerMeta,
+  PaletteItem: paletteItemMeta,
+  TileGrid: tileGridMeta,
+  Timeline: timelineMeta,
+  TreeItem: treeItemMeta,
+  TreeView: treeViewMeta,
+  ZoraDrawerContent: zoraDrawerContentMeta,
+  ZoraTabBar: zoraTabBarMeta,
+};

package/src/metadata/index.ts

@@ -0,0 +1,13 @@
+export { ZORA_COMPONENT_META } from './componentMeta';
+export type {
+  ZoraComponentBlueprint,
+  ZoraComponentCategory,
+  ZoraComponentI18nMeta,
+  ZoraComponentMeta,
+  ZoraComponentMetaRegistry,
+  ZoraComponentPropArrayItemSchema,
+  ZoraComponentPropSchema,
+  ZoraComponentPropType,
+  ZoraComponentPropValue,
+  ZoraComponentSlotMeta,
+} from './types';

package/src/metadata/types.ts

@@ -0,0 +1,74 @@
+export type ZoraComponentCategory = 'foundation' | 'component' | 'pattern' | 'layout';
+
+export type ZoraComponentPropType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'enum'
+  | 'color'
+  | 'spacing'
+  | 'radius'
+  | 'shadow'
+  | 'typographySize'
+  | 'typographyWeight'
+  | 'action'
+  | 'imageAsset'
+  | 'array';
+
+export type ZoraComponentPropValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly ZoraComponentPropValue[]
+  | { readonly [key: string]: ZoraComponentPropValue };
+
+export interface ZoraComponentPropArrayItemSchema {
+  key: string;
+  schema: ZoraComponentPropSchema;
+}
+
+export interface ZoraComponentPropSchema {
+  type: ZoraComponentPropType;
+  category: string;
+  label?: string;
+  enum?: readonly (string | number)[];
+  default?: ZoraComponentPropValue;
+  itemSchema?: readonly ZoraComponentPropArrayItemSchema[];
+}
+
+export interface ZoraComponentBlueprint {
+  label: string;
+  icon?: {
+    name: string;
+    provider?: string;
+  };
+  defaultProps?: Readonly<Record<string, ZoraComponentPropValue>>;
+}
+
+export interface ZoraComponentI18nMeta {
+  fields: readonly {
+    keyProp: string;
+    defaultTextProp: string;
+  }[];
+}
+
+export interface ZoraComponentSlotMeta {
+  label?: string;
+  allowedChildren?: readonly string[];
+}
+
+export interface ZoraComponentMeta {
+  name: string;
+  category: ZoraComponentCategory;
+  description?: string;
+  directManifestNode: boolean;
+  allowedChildren: readonly string[];
+  blueprint?: ZoraComponentBlueprint;
+  i18n?: ZoraComponentI18nMeta;
+  slots?: Readonly<Record<string, ZoraComponentSlotMeta>>;
+  note?: string;
+  props: Readonly<Record<string, ZoraComponentPropSchema>>;
+}
+
+export type ZoraComponentMetaRegistry = Readonly<Record<string, ZoraComponentMeta>>;

package/src/patterns/auth/meta.ts

@@ -0,0 +1,39 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+const AUTH_NOTE = 'Auth pattern component; not represented as a manifest node in v1.';
+
+export const forgotPasswordFormMeta = {
+  name: 'ForgotPasswordForm',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: AUTH_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const otpFormMeta = {
+  name: 'OtpForm',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: AUTH_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const signInFormMeta = {
+  name: 'SignInForm',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: AUTH_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const signUpFormMeta = {
+  name: 'SignUpForm',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: AUTH_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/patterns/collection-editor/meta.ts

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

package/src/patterns/confirm-dialog/meta.ts

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

package/src/patterns/disclosure-section/meta.ts

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

package/src/patterns/empty-state/meta.ts

@@ -0,0 +1,34 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const emptyStateMeta = {
+  name: 'EmptyState',
+  category: 'pattern',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Empty state',
+    defaultProps: {
+      title: 'Nothing here yet',
+      description: 'Try adding your first item.',
+    },
+  },
+  props: {
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+      default: 'Nothing here yet',
+    },
+    description: {
+      type: 'string',
+      category: 'Content',
+      label: 'Description',
+      default: 'Try adding your first item.',
+    },
+    eyebrow: {
+      type: 'string',
+      category: 'Content',
+      label: 'Eyebrow',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/patterns/filter-bar/meta.ts

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

package/src/patterns/image-preview/meta.ts

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

package/src/patterns/image-upload-field/meta.ts

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

package/src/patterns/inspector-field/meta.ts

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

package/src/patterns/list/meta.ts

@@ -0,0 +1,30 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+const LIST_NOTE = 'List pattern component; not represented as a manifest node in v1.';
+
+export const listMeta = {
+  name: 'List',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: LIST_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const listRowMeta = {
+  name: 'ListRow',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: LIST_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const listSectionMeta = {
+  name: 'ListSection',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: LIST_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/patterns/notice/meta.ts

@@ -0,0 +1,36 @@
+import type { ZoraComponentMeta } from '../../metadata';
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+
+export const noticeMeta = {
+  name: 'Notice',
+  category: 'pattern',
+  directManifestNode: true,
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  blueprint: {
+    label: 'Notice',
+    defaultProps: {
+      title: 'Notice',
+      tone: 'primary',
+    },
+  },
+  props: {
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+      default: 'Notice',
+    },
+    description: {
+      type: 'string',
+      category: 'Content',
+      label: 'Description',
+    },
+    tone: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Tone',
+      enum: ['primary', 'neutral', 'danger', 'success', 'warning'],
+      default: 'primary',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/patterns/panel/meta.ts

@@ -0,0 +1,46 @@
+import type { ZoraComponentMeta } from '../../metadata';
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+
+export const panelMeta = {
+  name: 'Panel',
+  category: 'pattern',
+  directManifestNode: true,
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  blueprint: {
+    label: 'Panel',
+    defaultProps: {
+      title: 'Panel',
+      tone: 'default',
+    },
+  },
+  props: {
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+    },
+    description: {
+      type: 'string',
+      category: 'Content',
+      label: 'Description',
+    },
+    eyebrow: {
+      type: 'string',
+      category: 'Content',
+      label: 'Eyebrow',
+    },
+    tone: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Tone',
+      enum: ['default', 'subtle', 'outline'],
+      default: 'default',
+    },
+    compact: {
+      type: 'boolean',
+      category: 'Layout',
+      label: 'Compact',
+      default: false,
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/patterns/responsive-panel/meta.ts

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

package/src/patterns/section-header/meta.ts

@@ -0,0 +1,34 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const sectionHeaderMeta = {
+  name: 'SectionHeader',
+  category: 'pattern',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Section header',
+    defaultProps: {
+      title: 'Section title',
+      description: 'Short description.',
+    },
+  },
+  props: {
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+      default: 'Section title',
+    },
+    description: {
+      type: 'string',
+      category: 'Content',
+      label: 'Description',
+      default: 'Short description.',
+    },
+    eyebrow: {
+      type: 'string',
+      category: 'Content',
+      label: 'Eyebrow',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/patterns/selection/SelectableItem.tsx

@@ -0,0 +1,93 @@
+import { ButtonBase } from '@ankhorage/surface';
+import React from 'react';
+import type { GestureResponderEvent } from 'react-native';
+
+import { useSelection } from './SelectionProvider';
+import type { SelectableItemProps, SelectableItemState, SelectionTrigger } from './types';
+
+function resolveTrigger(trigger: SelectionTrigger | undefined): SelectionTrigger {
+  return trigger ?? 'manual';
+}
+
+function isRenderProp(
+  children: SelectableItemProps['children'],
+): children is (state: SelectableItemState) => React.ReactNode {
+  return typeof children === 'function';
+}
+
+export function SelectableItem({ id, trigger, disabled = false, children }: SelectableItemProps) {
+  const selection = useSelection();
+  const resolvedTrigger = resolveTrigger(trigger);
+  const resolvedDisabled = selection.disabled || disabled;
+  const selected = selection.isSelected(id);
+
+  const select = React.useCallback(() => {
+    if (resolvedDisabled) return;
+    selection.select(id);
+  }, [id, resolvedDisabled, selection]);
+
+  const toggle = React.useCallback(() => {
+    if (resolvedDisabled) return;
+    selection.toggle(id);
+  }, [id, resolvedDisabled, selection]);
+
+  const clear = React.useCallback(() => {
+    if (selection.disabled) return;
+    selection.clear();
+  }, [selection]);
+
+  const itemState = React.useMemo<SelectableItemState>(() => {
+    return {
+      id,
+      selected,
+      disabled: resolvedDisabled,
+      mode: selection.mode,
+      select,
+      toggle,
+      clear,
+    };
+  }, [clear, id, resolvedDisabled, select, selected, selection.mode, toggle]);
+
+  // IMPORTANT:
+  // Do not pass `children` directly into ButtonBase. ButtonBase also supports function children,
+  // but its function signature receives interaction state, not SelectableItemState.
+  const content = isRenderProp(children) ? children(itemState) : children;
+
+  if (resolvedTrigger === 'manual') {
+    return <>{content}</>;
+  }
+
+  const handlePress = (event: GestureResponderEvent) => {
+    event.stopPropagation();
+    if (resolvedDisabled) return;
+    if (selection.mode === 'single') {
+      selection.select(id);
+      return;
+    }
+
+    selection.toggle(id);
+  };
+
+  const handleLongPress = (event: GestureResponderEvent) => {
+    event.stopPropagation();
+    if (resolvedDisabled) return;
+    if (selection.mode === 'single') {
+      selection.select(id);
+      return;
+    }
+
+    selection.toggle(id);
+  };
+
+  return (
+    <ButtonBase
+      accessibilityRole="button"
+      accessibilityState={{ disabled: resolvedDisabled, selected }}
+      disabled={resolvedDisabled}
+      onLongPress={resolvedTrigger === 'longPress' ? handleLongPress : undefined}
+      onPress={resolvedTrigger === 'press' ? handlePress : undefined}
+    >
+      {content}
+    </ButtonBase>
+  );
+}