@ankhorage/zora 1.2.0 → 1.4.0

package/src/patterns/selection/SelectionProvider.tsx

@@ -0,0 +1,102 @@
+import React from 'react';
+
+import { areIdsEqual, clearIds, normalizeIds, selectId, toggleId } from './resolveSelectionNextIds';
+import type { SelectionMode, SelectionProviderProps, UseSelectionResult } from './types';
+
+const MISSING_CONTEXT_MESSAGE =
+  'ZORA selection context is missing. Wrap this tree in <SelectionProvider>.';
+
+type SelectionContextValue = UseSelectionResult;
+
+const SelectionContext = React.createContext<SelectionContextValue | null>(null);
+
+function resolveMode(mode: SelectionMode | undefined): SelectionMode {
+  return mode ?? 'single';
+}
+
+function resolveDisabled(disabled: boolean | undefined): boolean {
+  return disabled ?? false;
+}
+
+export function useSelection(): UseSelectionResult {
+  const value = React.useContext(SelectionContext);
+  if (!value) {
+    throw new Error(MISSING_CONTEXT_MESSAGE);
+  }
+
+  return value;
+}
+
+export function SelectionProvider({
+  children,
+  selectedIds,
+  defaultSelectedIds,
+  mode,
+  disabled,
+  onSelectionChange,
+}: SelectionProviderProps) {
+  const resolvedMode = resolveMode(mode);
+  const resolvedDisabled = resolveDisabled(disabled);
+  const isControlled = selectedIds !== undefined;
+
+  const [uncontrolledIds, setUncontrolledIds] = React.useState<readonly string[]>(
+    defaultSelectedIds ?? [],
+  );
+
+  const rawIds = isControlled ? selectedIds : uncontrolledIds;
+  const currentNormalizedIds = normalizeIds(rawIds, resolvedMode);
+
+  const selectedIdSet = React.useMemo(() => new Set(currentNormalizedIds), [currentNormalizedIds]);
+
+  const commitSelectionChange = React.useCallback(
+    (nextNormalizedIds: readonly string[]) => {
+      if (resolvedDisabled) return;
+      if (areIdsEqual(nextNormalizedIds, currentNormalizedIds)) return;
+
+      onSelectionChange?.(nextNormalizedIds);
+
+      if (!isControlled) {
+        setUncontrolledIds(nextNormalizedIds);
+      }
+    },
+    [currentNormalizedIds, isControlled, onSelectionChange, resolvedDisabled],
+  );
+
+  const clear = React.useCallback(() => {
+    commitSelectionChange(normalizeIds(clearIds(), resolvedMode));
+  }, [commitSelectionChange, resolvedMode]);
+
+  const select = React.useCallback(
+    (id: string) => {
+      const nextIds = selectId({ mode: resolvedMode, ids: currentNormalizedIds, id });
+      const nextNormalizedIds = normalizeIds(nextIds, resolvedMode);
+      commitSelectionChange(nextNormalizedIds);
+    },
+    [commitSelectionChange, currentNormalizedIds, resolvedMode],
+  );
+
+  const toggle = React.useCallback(
+    (id: string) => {
+      const nextIds = toggleId({ mode: resolvedMode, ids: currentNormalizedIds, id });
+      const nextNormalizedIds = normalizeIds(nextIds, resolvedMode);
+      commitSelectionChange(nextNormalizedIds);
+    },
+    [commitSelectionChange, currentNormalizedIds, resolvedMode],
+  );
+
+  const value = React.useMemo<UseSelectionResult>(() => {
+    return {
+      mode: resolvedMode,
+      disabled: resolvedDisabled,
+      selectedIds: currentNormalizedIds,
+      selectedCount: currentNormalizedIds.length,
+      hasSelection: currentNormalizedIds.length > 0,
+      isSelected: (id: string) => selectedIdSet.has(id),
+      select,
+      toggle,
+      clear,
+    };
+  }, [clear, currentNormalizedIds, resolvedDisabled, resolvedMode, select, selectedIdSet, toggle]);
+
+  return <SelectionContext.Provider value={value}>{children}</SelectionContext.Provider>;
+}

package/src/patterns/selection/index.ts

@@ -0,0 +1,10 @@
+export { SelectableItem } from './SelectableItem';
+export { SelectionProvider, useSelection } from './SelectionProvider';
+export type {
+  SelectableItemProps,
+  SelectableItemState,
+  SelectionMode,
+  SelectionProviderProps,
+  SelectionTrigger,
+  UseSelectionResult,
+} from './types';

package/src/patterns/selection/meta.ts

@@ -0,0 +1,21 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+const SELECTION_NOTE = 'Selection pattern component; not represented as a manifest node in v1.';
+
+export const selectableItemMeta = {
+  name: 'SelectableItem',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: SELECTION_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const selectionProviderMeta = {
+  name: 'SelectionProvider',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: SELECTION_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/patterns/selection/resolveSelectionNextIds.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'bun:test';
+
+import { areIdsEqual, clearIds, normalizeIds, selectId, toggleId } from './resolveSelectionNextIds';
+import type { SelectionMode } from './types';
+
+describe('resolveSelectionNextIds', () => {
+  test('normalizeIds removes duplicates, preserves order', () => {
+    expect(normalizeIds(['a', 'b', 'a', 'c'], 'multi')).toEqual(['a', 'b', 'c']);
+  });
+
+  test('normalizeIds keeps only first id in single mode', () => {
+    expect(normalizeIds(['a', 'b', 'c'], 'single')).toEqual(['a']);
+  });
+
+  test('normalizeIds treats undefined as empty', () => {
+    expect(normalizeIds(undefined, 'multi')).toEqual([]);
+  });
+
+  test('areIdsEqual compares order', () => {
+    expect(areIdsEqual(['a'], ['a'])).toBeTrue();
+    expect(areIdsEqual(['a'], ['b'])).toBeFalse();
+    expect(areIdsEqual(['a', 'b'], ['a', 'b'])).toBeTrue();
+    expect(areIdsEqual(['a', 'b'], ['b', 'a'])).toBeFalse();
+  });
+
+  test('clearIds returns empty selection', () => {
+    expect(clearIds()).toEqual([]);
+  });
+
+  test('selectId replaces selection in single mode', () => {
+    expect(selectId({ mode: 'single', ids: ['a'], id: 'b' })).toEqual(['b']);
+  });
+
+  test('selectId adds id in multi mode when missing', () => {
+    expect(selectId({ mode: 'multi', ids: ['a'], id: 'b' })).toEqual(['a', 'b']);
+  });
+
+  test('selectId is no-op in multi mode when already selected', () => {
+    const ids = ['a', 'b'];
+    expect(selectId({ mode: 'multi', ids, id: 'b' })).toBe(ids);
+  });
+
+  test('toggleId clears id when already selected (single mode)', () => {
+    expect(toggleId({ mode: 'single', ids: ['a'], id: 'a' })).toEqual([]);
+  });
+
+  test('toggleId selects id when not selected (single mode)', () => {
+    expect(toggleId({ mode: 'single', ids: [], id: 'a' })).toEqual(['a']);
+  });
+
+  test('toggleId toggles membership (multi mode)', () => {
+    expect(toggleId({ mode: 'multi', ids: ['a'], id: 'b' })).toEqual(['a', 'b']);
+    expect(toggleId({ mode: 'multi', ids: ['a', 'b'], id: 'b' })).toEqual(['a']);
+  });
+
+  test('mode-change normalization example', () => {
+    const internalIds = ['a', 'b'];
+    const mode: SelectionMode = 'single';
+    expect(normalizeIds(internalIds, mode)).toEqual(['a']);
+  });
+});

package/src/patterns/selection/resolveSelectionNextIds.ts

@@ -0,0 +1,71 @@
+import type { SelectionMode } from './types';
+
+export function normalizeIds(
+  ids: readonly string[] | undefined,
+  mode: SelectionMode,
+): readonly string[] {
+  const uniqueIds: string[] = [];
+  const seen = new Set<string>();
+
+  for (const id of ids ?? []) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    uniqueIds.push(id);
+    if (mode === 'single') break;
+  }
+
+  return uniqueIds;
+}
+
+export function areIdsEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] !== b[index]) return false;
+  }
+
+  return true;
+}
+
+export function clearIds(): readonly string[] {
+  return [];
+}
+
+export function selectId({
+  mode,
+  ids,
+  id,
+}: {
+  mode: SelectionMode;
+  ids: readonly string[];
+  id: string;
+}): readonly string[] {
+  if (mode === 'single') {
+    return [id];
+  }
+
+  if (ids.includes(id)) {
+    return ids;
+  }
+
+  return [...ids, id];
+}
+
+export function toggleId({
+  mode,
+  ids,
+  id,
+}: {
+  mode: SelectionMode;
+  ids: readonly string[];
+  id: string;
+}): readonly string[] {
+  if (ids.includes(id)) {
+    return ids.filter((existingId) => existingId !== id);
+  }
+
+  if (mode === 'single') {
+    return [id];
+  }
+
+  return [...ids, id];
+}

package/src/patterns/selection/types.ts

@@ -0,0 +1,43 @@
+import type React from 'react';
+
+export type SelectionMode = 'single' | 'multi';
+
+export type SelectionTrigger = 'press' | 'longPress' | 'manual';
+
+export interface SelectionProviderProps {
+  children: React.ReactNode;
+  selectedIds?: readonly string[];
+  defaultSelectedIds?: readonly string[];
+  mode?: SelectionMode;
+  disabled?: boolean;
+  onSelectionChange?: (ids: readonly string[]) => void;
+}
+
+export interface UseSelectionResult {
+  mode: SelectionMode;
+  disabled: boolean;
+  selectedIds: readonly string[];
+  selectedCount: number;
+  hasSelection: boolean;
+  isSelected: (id: string) => boolean;
+  select: (id: string) => void;
+  toggle: (id: string) => void;
+  clear: () => void;
+}
+
+export interface SelectableItemState {
+  id: string;
+  selected: boolean;
+  disabled: boolean;
+  mode: SelectionMode;
+  select: () => void;
+  toggle: () => void;
+  clear: () => void;
+}
+
+export interface SelectableItemProps {
+  id: string;
+  trigger?: SelectionTrigger;
+  disabled?: boolean;
+  children: React.ReactNode | ((state: SelectableItemState) => React.ReactNode);
+}

package/src/patterns/settings-row/meta.ts

@@ -0,0 +1,40 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const settingsRowMeta = {
+  name: 'SettingsRow',
+  category: 'pattern',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Settings row',
+    defaultProps: {
+      title: 'Setting',
+      description: 'Setting description.',
+    },
+  },
+  props: {
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+      default: 'Setting',
+    },
+    description: {
+      type: 'string',
+      category: 'Content',
+      label: 'Description',
+      default: 'Setting description.',
+    },
+    meta: {
+      type: 'string',
+      category: 'Content',
+      label: 'Meta',
+    },
+    disabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Disabled',
+      default: false,
+    },
+  },
+} as const satisfies ZoraComponentMeta;

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

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

package/src/patterns/theme-composer/meta.ts

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

package/src/patterns/tile-grid/meta.ts

@@ -0,0 +1,21 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+const TILE_GRID_NOTE = 'Tile grid pattern component; not represented as a manifest node in v1.';
+
+export const paletteItemMeta = {
+  name: 'PaletteItem',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: TILE_GRID_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const tileGridMeta = {
+  name: 'TileGrid',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: TILE_GRID_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/patterns/timeline/meta.ts

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

package/src/patterns/tree-view/meta.ts

@@ -0,0 +1,21 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+const TREE_NOTE = 'Tree view pattern component; not represented as a manifest node in v1.';
+
+export const treeItemMeta = {
+  name: 'TreeItem',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: TREE_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const treeViewMeta = {
+  name: 'TreeView',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: TREE_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/patterns/zora-drawer-content/meta.ts

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

package/src/patterns/zora-tab-bar/meta.ts

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

package/src/showcaseCoverage.test.ts

@@ -86,6 +86,9 @@ const REQUIRED_SHOWCASE_COVERAGE = {
     'DisclosureSection',
     'EmptyState',
     'FilterBar',
+    'SelectableItem',
+    'SelectionProvider',
+    'useSelection',
     'List',
     'ListRow',
     'ListSection',