@ankhorage/zora 20.0.2 → 20.1.1

package/src/features/tree-view/adapters/inbound/web-artifact/TreeItemRow.tsx

@@ -0,0 +1,197 @@
+import React from 'react';
+
+import type { TreeItemNode, TreeItemRenderProps } from './TreeView';
+
+/*** Render one recursive browser tree row while keeping selection and expansion independent. */
+export function TreeItemRow<TId extends string>(props: TreeItemRowProps<TId>) {
+  const { node } = props;
+  const hasChildren = node.children !== undefined && node.children.length > 0;
+  const expanded = props.expandedIds.includes(node.id);
+  const selected = props.selectedId === node.id;
+  const content = props.renderItem?.({
+    node,
+    depth: props.depth,
+    selected,
+    expanded,
+    hasChildren,
+  }) ?? <TreeItemDefaultContent node={node} />;
+
+  return (
+    <>
+      <div
+        aria-disabled={node.disabled === true ? true : undefined}
+        aria-expanded={hasChildren ? expanded : undefined}
+        aria-selected={selected}
+        onClick={() => selectNode(props)}
+        onKeyDown={(event) => selectNodeFromKeyboard(event, props)}
+        role="treeitem"
+        tabIndex={node.disabled || props.onSelect === undefined ? undefined : 0}
+        style={createRowStyle(props.depth, selected, node.disabled, props.onSelect !== undefined)}
+      >
+        {content}
+        <TreeItemActions actions={node.actions} />
+        <TreeItemExpander
+          expanded={expanded}
+          hasChildren={hasChildren}
+          nodeId={node.id}
+          onToggleExpand={props.onToggleExpand}
+        />
+      </div>
+      {hasChildren && expanded ? <TreeItemChildren {...props} /> : null}
+    </>
+  );
+}
+
+interface TreeItemRowProps<TId extends string> {
+  readonly node: TreeItemNode<TId>;
+  readonly depth: number;
+  readonly selectedId?: TId;
+  readonly expandedIds: readonly TId[];
+  readonly onSelect?: (id: TId) => void;
+  readonly onToggleExpand: (id: TId) => void;
+  readonly renderItem?: (props: TreeItemRenderProps<TId>) => React.ReactNode;
+}
+
+/*** Render the default browser tree-row label, icon, and metadata. */
+function TreeItemDefaultContent<TId extends string>({
+  node,
+}: {
+  readonly node: TreeItemNode<TId>;
+}) {
+  return (
+    <>
+      {node.icon === undefined ? null : (
+        <span aria-hidden="true" style={ICON_STYLE}>
+          {node.icon}
+        </span>
+      )}
+      <span style={LABEL_STYLE}>{node.label}</span>
+      {node.meta === undefined ? null : <span style={META_STYLE}>{node.meta}</span>}
+    </>
+  );
+}
+
+/*** Isolate optional row actions so their pointer events do not select the tree item. */
+function TreeItemActions({ actions }: { readonly actions?: React.ReactNode }) {
+  if (actions === undefined) return null;
+  return (
+    <span
+      onClick={(event) => event.stopPropagation()}
+      onKeyDown={(event) => event.stopPropagation()}
+      style={INLINE_STYLE}
+    >
+      {actions}
+    </span>
+  );
+}
+
+/*** Render the independent expansion control for a tree row with children. */
+function TreeItemExpander<TId extends string>(props: {
+  readonly expanded: boolean;
+  readonly hasChildren: boolean;
+  readonly nodeId: TId;
+  readonly onToggleExpand: (id: TId) => void;
+}) {
+  if (!props.hasChildren) return null;
+  return (
+    <button
+      aria-label={props.expanded ? 'Collapse' : 'Expand'}
+      onClick={(event) => {
+        event.stopPropagation();
+        props.onToggleExpand(props.nodeId);
+      }}
+      style={EXPANDER_STYLE}
+      type="button"
+    >
+      {props.expanded ? '⌄' : '›'}
+    </button>
+  );
+}
+
+/*** Render expanded descendants recursively. */
+function TreeItemChildren<TId extends string>(props: TreeItemRowProps<TId>) {
+  return (
+    <div role="group">
+      {props.node.children?.map((child) => (
+        <TreeItemRow {...props} key={child.id} depth={props.depth + 1} node={child} />
+      ))}
+    </div>
+  );
+}
+
+/*** Select a row from pointer activation when it is interactive. */
+function selectNode<TId extends string>(props: TreeItemRowProps<TId>) {
+  if (!props.node.disabled) props.onSelect?.(props.node.id);
+}
+
+/*** Select a row from keyboard activation while preserving native navigation keys. */
+function selectNodeFromKeyboard<TId extends string>(
+  event: React.KeyboardEvent<HTMLDivElement>,
+  props: TreeItemRowProps<TId>,
+) {
+  if (props.node.disabled || (event.key !== 'Enter' && event.key !== ' ')) return;
+  event.preventDefault();
+  props.onSelect?.(props.node.id);
+}
+
+/*** Resolve browser row presentation from the interaction state. */
+function createRowStyle(
+  depth: number,
+  selected: boolean,
+  disabled: boolean | undefined,
+  selectable: boolean,
+): React.CSSProperties {
+  return {
+    ...ROW_STYLE,
+    background: selected ? 'color-mix(in srgb, currentColor 10%, transparent)' : 'transparent',
+    cursor: disabled ? 'default' : selectable ? 'pointer' : 'inherit',
+    opacity: disabled ? 0.5 : 1,
+    paddingLeft: depth * 16 + 6,
+  };
+}
+
+const ROW_STYLE = {
+  alignItems: 'center',
+  borderRadius: 6,
+  display: 'flex',
+  gap: 6,
+  minHeight: 28,
+  paddingRight: 4,
+  userSelect: 'none',
+} as const satisfies React.CSSProperties;
+
+const INLINE_STYLE = {
+  display: 'inline-flex',
+  flexShrink: 0,
+} as const satisfies React.CSSProperties;
+
+const ICON_STYLE = INLINE_STYLE;
+
+const LABEL_STYLE = {
+  flex: 1,
+  minWidth: 0,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+} as const satisfies React.CSSProperties;
+
+const META_STYLE = {
+  flexShrink: 0,
+  opacity: 0.65,
+} as const satisfies React.CSSProperties;
+
+const EXPANDER_STYLE = {
+  alignItems: 'center',
+  appearance: 'none',
+  background: 'transparent',
+  border: 0,
+  color: 'inherit',
+  cursor: 'pointer',
+  display: 'inline-flex',
+  flexShrink: 0,
+  font: 'inherit',
+  height: 24,
+  justifyContent: 'center',
+  padding: 0,
+  width: 24,
+} as const satisfies React.CSSProperties;

package/src/features/tree-view/adapters/inbound/web-artifact/TreeView.test.tsx

@@ -0,0 +1,28 @@
+import { expect, test } from 'bun:test';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import { TreeView } from './TreeView';
+
+test('renders a standalone web tree without a ZORA or React Native provider', () => {
+  const markup = renderToStaticMarkup(
+    <TreeView
+      defaultExpandedIds={['src']}
+      nodes={[
+        {
+          id: 'src',
+          label: 'src',
+          icon: <span>folder</span>,
+          children: [{ id: 'index', label: 'index.ts' }],
+        },
+      ]}
+      selectedId="index"
+    />,
+  );
+
+  expect(markup).toContain('role="tree"');
+  expect(markup).toContain('role="treeitem"');
+  expect(markup).toContain('folder');
+  expect(markup).toContain('index.ts');
+  expect(markup).toContain('aria-selected="true"');
+});

package/src/features/tree-view/adapters/inbound/web-artifact/TreeView.tsx

@@ -0,0 +1,91 @@
+import React from 'react';
+
+import { toggleExpandedIds } from '../../../utils/toggleExpandedIds';
+import { TreeItemRow } from './TreeItemRow';
+
+export interface TreeItemNode<TId extends string = string> {
+  readonly id: TId;
+  readonly label: React.ReactNode;
+  readonly icon?: React.ReactNode;
+  readonly children?: readonly TreeItemNode<TId>[];
+  readonly disabled?: boolean;
+  readonly meta?: React.ReactNode;
+  readonly actions?: React.ReactNode;
+}
+
+export interface TreeItemRenderProps<TId extends string = string> {
+  readonly node: TreeItemNode<TId>;
+  readonly depth: number;
+  readonly selected: boolean;
+  readonly expanded: boolean;
+  readonly hasChildren: boolean;
+}
+
+export interface TreeViewProps<TId extends string = string> {
+  readonly nodes: readonly TreeItemNode<TId>[];
+  readonly selectedId?: TId;
+  readonly expandedIds?: readonly TId[];
+  readonly defaultExpandedIds?: readonly TId[];
+  readonly onSelect?: (id: TId) => void;
+  readonly onExpandedChange?: (ids: readonly TId[]) => void;
+  readonly renderItem?: (props: TreeItemRenderProps<TId>) => React.ReactNode;
+  readonly className?: string;
+  readonly style?: React.CSSProperties;
+  readonly ariaLabel?: string;
+}
+
+/*** Render the standalone browser TreeView artifact without React Native runtime dependencies. */
+export function TreeView<TId extends string = string>({
+  nodes,
+  selectedId,
+  expandedIds: controlledExpandedIds,
+  defaultExpandedIds,
+  onSelect,
+  onExpandedChange,
+  renderItem,
+  className,
+  style,
+  ariaLabel = 'Tree',
+}: TreeViewProps<TId>) {
+  const [internalExpandedIds, setInternalExpandedIds] = React.useState<readonly TId[]>(
+    defaultExpandedIds ?? [],
+  );
+  const isControlled = controlledExpandedIds !== undefined;
+  const expandedIds = isControlled ? controlledExpandedIds : internalExpandedIds;
+  const handleToggleExpand = React.useCallback(
+    (id: TId) => {
+      const nextExpandedIds = toggleExpandedIds(expandedIds, id);
+      if (!isControlled) setInternalExpandedIds(nextExpandedIds);
+      onExpandedChange?.(nextExpandedIds);
+    },
+    [expandedIds, isControlled, onExpandedChange],
+  );
+
+  return (
+    <div
+      aria-label={ariaLabel}
+      className={className}
+      role="tree"
+      style={{ ...TREE_STYLE, ...style }}
+    >
+      {nodes.map((node) => (
+        <TreeItemRow
+          key={node.id}
+          depth={0}
+          expandedIds={expandedIds}
+          node={node}
+          onSelect={onSelect}
+          onToggleExpand={handleToggleExpand}
+          renderItem={renderItem}
+          selectedId={selectedId}
+        />
+      ))}
+    </div>
+  );
+}
+
+const TREE_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  minWidth: 0,
+} as const satisfies React.CSSProperties;

package/src/features/tree-view/utils/toggleExpandedIds.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from 'bun:test';
+
+import { toggleExpandedIds } from './toggleExpandedIds';
+
+test('adds and removes expanded tree ids immutably', () => {
+  const initial = ['src'] as const;
+  const expanded = toggleExpandedIds(initial, 'test');
+
+  expect(expanded).toEqual(['src', 'test']);
+  expect(initial).toEqual(['src']);
+  expect(toggleExpandedIds(expanded, 'src')).toEqual(['test']);
+});

package/src/features/tree-view/utils/toggleExpandedIds.ts

@@ -0,0 +1,9 @@
+/*** Toggle one tree node id while preserving immutable expansion state. */
+export function toggleExpandedIds<TId extends string>(
+  expandedIds: readonly TId[],
+  id: TId,
+): readonly TId[] {
+  return expandedIds.includes(id)
+    ? expandedIds.filter((expandedId) => expandedId !== id)
+    : [...expandedIds, id];
+}

package/src/features/web-component-artifact/adapters/outbound/node/createNodeWebComponentArtifactFileSystem.ts

@@ -0,0 +1,22 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import type { WebComponentArtifactFileSystemPort } from '../../../application/ports/outbound/WebComponentArtifactFileSystemPort';
+
+/*** Create the Node filesystem adapter used by ZORA web-component materialization. */
+export function createNodeWebComponentArtifactFileSystem(): WebComponentArtifactFileSystemPort {
+  return {
+    joinPath(...parts) {
+      return join(...parts);
+    },
+    async ensureDirectoryAsync(path) {
+      await mkdir(path, { recursive: true });
+    },
+    async readTextFileAsync(path) {
+      return await readFile(path, 'utf8');
+    },
+    async writeTextFileAsync(path, content) {
+      await writeFile(path, content, 'utf8');
+    },
+  };
+}

package/src/features/web-component-artifact/application/ports/outbound/WebComponentArtifactFileSystemPort.ts

@@ -0,0 +1,6 @@
+export interface WebComponentArtifactFileSystemPort {
+  joinPath(...parts: readonly string[]): string;
+  ensureDirectoryAsync(path: string): Promise<void>;
+  readTextFileAsync(path: string): Promise<string>;
+  writeTextFileAsync(path: string, content: string): Promise<void>;
+}

package/src/features/web-component-artifact/application/use-cases/materializeWebComponentArtifactAsync.test.ts

@@ -0,0 +1,84 @@
+import { expect, test } from 'bun:test';
+
+import type { WebComponentArtifactFileSystemPort } from '../ports/outbound/WebComponentArtifactFileSystemPort';
+import { materializeWebComponentArtifactAsync } from './materializeWebComponentArtifactAsync';
+
+test('materializes the packaged tree-view web artifact without source ownership transfer', async () => {
+  const packageRoot = '/package';
+  const outputDirectory = '/consumer/src/generated/zora/tree-view';
+  const writes = new Map<string, string>();
+  const sources = new Map<string, string>([
+    ['/package/web-dist/tree-view/TreeView.js', 'export const TreeView = 1;\n'],
+    ['/package/web-dist/tree-view/TreeView.d.ts', 'export declare const TreeView: unknown;\n'],
+  ]);
+  const fileSystem = createFakeFileSystem(sources, writes);
+
+  const result = await materializeWebComponentArtifactAsync(
+    {
+      component: 'tree-view',
+      outputDirectory,
+      packageRoot,
+      packageVersion: '1.2.3',
+    },
+    fileSystem,
+  );
+
+  expect(result.platform).toBe('web');
+  expect(result.createdFiles).toEqual([
+    `${outputDirectory}/TreeView.js`,
+    `${outputDirectory}/TreeView.d.ts`,
+    `${outputDirectory}/zora-artifact.json`,
+  ]);
+  expect(writes.get(`${outputDirectory}/TreeView.js`)).toStartWith(
+    '// Generated by @ankhorage/zora v1.2.3. Do not edit manually.',
+  );
+  expect(writes.get(`${outputDirectory}/zora-artifact.json`)).toContain(
+    '"owner": "@ankhorage/zora"',
+  );
+});
+
+test('rejects unsupported web components explicitly', async () => {
+  const fileSystem = createFakeFileSystem(new Map(), new Map());
+  let caught: unknown;
+
+  try {
+    await materializeWebComponentArtifactAsync(
+      {
+        component: 'unknown',
+        outputDirectory: '/consumer',
+        packageRoot: '/package',
+        packageVersion: '1.2.3',
+      },
+      fileSystem,
+    );
+  } catch (error) {
+    caught = error;
+  }
+
+  expect(caught).toBeInstanceOf(Error);
+  expect((caught as Error).message).toBe('Unsupported ZORA web component: unknown');
+});
+
+/*** Create a portable fake for the artifact filesystem port. */
+function createFakeFileSystem(
+  sources: ReadonlyMap<string, string>,
+  writes: Map<string, string>,
+): WebComponentArtifactFileSystemPort {
+  return {
+    joinPath(...parts) {
+      return parts.join('/').replaceAll('//', '/');
+    },
+    ensureDirectoryAsync() {
+      return Promise.resolve();
+    },
+    readTextFileAsync(path) {
+      const source = sources.get(path);
+      if (source === undefined) return Promise.reject(new Error(`Missing test source: ${path}`));
+      return Promise.resolve(source);
+    },
+    writeTextFileAsync(path, content) {
+      writes.set(path, content);
+      return Promise.resolve();
+    },
+  };
+}

package/src/features/web-component-artifact/application/use-cases/materializeWebComponentArtifactAsync.ts

@@ -0,0 +1,83 @@
+import type { WebComponentArtifactFileSystemPort } from '../ports/outbound/WebComponentArtifactFileSystemPort';
+
+export interface MaterializeWebComponentArtifactInput {
+  readonly component: string;
+  readonly outputDirectory: string;
+  readonly packageRoot: string;
+  readonly packageVersion: string;
+}
+
+export interface MaterializeWebComponentArtifactResult {
+  readonly component: string;
+  readonly createdFiles: readonly string[];
+  readonly outputDirectory: string;
+  readonly platform: 'web';
+}
+
+/*** Materialize one replaceable web-only component artifact from the published ZORA build. */
+export async function materializeWebComponentArtifactAsync(
+  input: MaterializeWebComponentArtifactInput,
+  fileSystem: WebComponentArtifactFileSystemPort,
+): Promise<MaterializeWebComponentArtifactResult> {
+  const artifact = resolveWebArtifact(input.component);
+  const sourceDirectory = fileSystem.joinPath(input.packageRoot, 'web-dist', artifact.directory);
+  await fileSystem.ensureDirectoryAsync(input.outputDirectory);
+
+  const createdFiles = await Promise.all(
+    artifact.files.map(async (fileName) => {
+      const sourcePath = fileSystem.joinPath(sourceDirectory, fileName);
+      const targetPath = fileSystem.joinPath(input.outputDirectory, fileName);
+      const source = await fileSystem.readTextFileAsync(sourcePath);
+      await fileSystem.writeTextFileAsync(
+        targetPath,
+        createGeneratedSource(input.packageVersion, source),
+      );
+      return targetPath;
+    }),
+  );
+
+  const metadataPath = fileSystem.joinPath(input.outputDirectory, 'zora-artifact.json');
+  await fileSystem.writeTextFileAsync(
+    metadataPath,
+    `${JSON.stringify(
+      {
+        generated: true,
+        owner: '@ankhorage/zora',
+        version: input.packageVersion,
+        component: input.component,
+        platform: 'web',
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  return {
+    component: input.component,
+    createdFiles: [...createdFiles, metadataPath],
+    outputDirectory: input.outputDirectory,
+    platform: 'web',
+  };
+}
+
+interface WebArtifactDefinition {
+  readonly directory: string;
+  readonly files: readonly string[];
+}
+
+/*** Resolve the canonical packaged web artifact for a requested component. */
+function resolveWebArtifact(component: string): WebArtifactDefinition {
+  if (component === 'tree-view') {
+    return {
+      directory: 'tree-view',
+      files: ['TreeView.js', 'TreeView.d.ts'],
+    };
+  }
+
+  throw new Error(`Unsupported ZORA web component: ${component}`);
+}
+
+/*** Add a generated-file marker without changing the compiled artifact semantics. */
+function createGeneratedSource(packageVersion: string, source: string): string {
+  return `// Generated by @ankhorage/zora v${packageVersion}. Do not edit manually.\n${source}`;
+}

package/src/features/web-component-artifact/composition/materializeWebComponentArtifactWithNodeAsync.ts

@@ -0,0 +1,16 @@
+import { createNodeWebComponentArtifactFileSystem } from '../adapters/outbound/node/createNodeWebComponentArtifactFileSystem';
+import {
+  materializeWebComponentArtifactAsync,
+  type MaterializeWebComponentArtifactInput,
+  type MaterializeWebComponentArtifactResult,
+} from '../application/use-cases/materializeWebComponentArtifactAsync';
+
+/*** Compose the Node filesystem adapter with the web-component materialization use case. */
+export async function materializeWebComponentArtifactWithNodeAsync(
+  input: MaterializeWebComponentArtifactInput,
+): Promise<MaterializeWebComponentArtifactResult> {
+  return await materializeWebComponentArtifactAsync(
+    input,
+    createNodeWebComponentArtifactFileSystem(),
+  );
+}

package/src/platformAcceptance.test.ts

@@ -9,6 +9,6 @@ test('passes the isolated Surface and RN Web 0.21 acceptance suite', () => {
   const output = `${subprocess.stdout.toString()}\n${subprocess.stderr.toString()}`;
 
   expect(subprocess.exitCode, output).toBe(0);
-  expect(output).toContain('10 pass');
+  expect(output).toContain('11 pass');
   expect(output).toContain('0 fail');
 });

package/src/structureOwnership.test.ts

@@ -3,13 +3,13 @@ import { existsSync, readdirSync } from 'node:fs';
 import { describe, expect, test } from 'bun:test';
 
 describe('src ownership', () => {
-  test('keeps only feature and type owner directories at the package source root', () => {
+  test('keeps the required CLI, feature, and type owner directories at the package source root', () => {
     const directories = readdirSync('src', { withFileTypes: true })
       .filter((entry) => entry.isDirectory())
       .map((entry) => entry.name)
       .sort();
 
-    expect(directories).toEqual(['features', 'types']);
+    expect(directories).toEqual(['cli', 'features', 'types']);
   });
 
   test('does not reintroduce technical ownership roots', () => {

package/web-dist/tree-view/TreeView.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+export interface TreeItemNode<TId extends string = string> {
+    readonly id: TId;
+    readonly label: React.ReactNode;
+    readonly icon?: React.ReactNode;
+    readonly children?: readonly TreeItemNode<TId>[];
+    readonly disabled?: boolean;
+    readonly meta?: React.ReactNode;
+    readonly actions?: React.ReactNode;
+}
+export interface TreeItemRenderProps<TId extends string = string> {
+    readonly node: TreeItemNode<TId>;
+    readonly depth: number;
+    readonly selected: boolean;
+    readonly expanded: boolean;
+    readonly hasChildren: boolean;
+}
+export interface TreeViewProps<TId extends string = string> {
+    readonly nodes: readonly TreeItemNode<TId>[];
+    readonly selectedId?: TId;
+    readonly expandedIds?: readonly TId[];
+    readonly defaultExpandedIds?: readonly TId[];
+    readonly onSelect?: (id: TId) => void;
+    readonly onExpandedChange?: (ids: readonly TId[]) => void;
+    readonly renderItem?: (props: TreeItemRenderProps<TId>) => React.ReactNode;
+    readonly className?: string;
+    readonly style?: React.CSSProperties;
+    readonly ariaLabel?: string;
+}
+/*** Render the standalone browser TreeView artifact without React Native runtime dependencies. */
+export declare function TreeView<TId extends string = string>({ nodes, selectedId, expandedIds: controlledExpandedIds, defaultExpandedIds, onSelect, onExpandedChange, renderItem, className, style, ariaLabel, }: TreeViewProps<TId>): React.JSX.Element;
+//# sourceMappingURL=TreeView.d.ts.map