@dxos/react-ui-list 0.9.1-main.c7dcc2e112 → 0.10.0

package/src/components/Treegrid/Treegrid.stories.tsx

@@ -0,0 +1,132 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { random } from '@dxos/random';
+import { Icon } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { Treegrid, TREEGRID_PARENT_OF_SEPARATOR, TREEGRID_PATH_SEPARATOR } from './Treegrid';
+
+random.seed(1234);
+
+type StorybookNode = {
+  id: string;
+  title: string;
+  icon?: string;
+  nodes?: StorybookNode[];
+};
+
+type StorybookIteratorNode = {
+  node: StorybookNode;
+  path: string[];
+  parentOf?: string[];
+};
+
+const content = {
+  id: 'root',
+  title: 'Root',
+  nodes: [
+    {
+      id: random.string.uuid(),
+      title: 'Personal Space',
+      icon: 'ph--house--regular',
+      nodes: [
+        { id: random.string.uuid(), title: random.commerce.productName() },
+        { id: random.string.uuid(), title: random.commerce.productName() },
+        {
+          id: random.string.uuid(),
+          title: random.commerce.productName(),
+          nodes: [
+            {
+              id: random.string.uuid(),
+              title: random.commerce.productName(),
+              nodes: [
+                { id: random.string.uuid(), title: random.commerce.productName() },
+                { id: random.string.uuid(), title: random.commerce.productName() },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+    {
+      id: random.string.uuid(),
+      title: random.commerce.productName(),
+      icon: 'ph--planet--regular',
+      nodes: [{ id: random.string.uuid(), title: random.commerce.productName() }],
+    },
+    { id: random.string.uuid(), title: random.commerce.productName(), icon: 'ph--sailboat--regular' },
+    { id: random.string.uuid(), title: random.commerce.productName(), icon: 'ph--planet--regular' },
+  ],
+} as StorybookNode;
+
+function* visitor(node: StorybookNode, isOpen?: (node: StorybookNode) => boolean): Generator<StorybookIteratorNode> {
+  // `parentOf` must reference rows by their full path-based id (the row's DOM id) so `aria-owns` resolves.
+  const stack: StorybookIteratorNode[] = [
+    {
+      node,
+      path: [node.id],
+      parentOf: (node.nodes ?? []).map(({ id }) => [node.id, id].join(TREEGRID_PATH_SEPARATOR)),
+    },
+  ];
+  while (stack.length > 0) {
+    const { node, path, parentOf } = stack.pop()!;
+    if (path.length > 1) {
+      yield { node, path, parentOf };
+    }
+
+    const children = Array.from(node.nodes ?? []);
+    if (path.length === 1 || isOpen?.(node)) {
+      for (let i = children.length - 1; i >= 0; i--) {
+        const child = children[i];
+        const childPath = [...path, child.id];
+        stack.push({
+          node: child,
+          path: childPath,
+          ...((child.nodes?.length ?? 0) > 0 && {
+            parentOf: child.nodes!.map(({ id }) => [...childPath, id].join(TREEGRID_PATH_SEPARATOR)),
+          }),
+        });
+      }
+    }
+  }
+}
+
+const flattenedContent = Array.from(visitor(content, () => true));
+
+// Two columns (name + child count) with row dividers so the grid structure is visible — a
+// single-column treegrid reads as a plain list.
+const DefaultStory = () => (
+  <Treegrid.Root gridTemplateColumns='1fr min-content' classNames='gap-x-4 divide-y divide-separator'>
+    {flattenedContent.map(({ node, parentOf, path }) => (
+      <Treegrid.Row
+        key={node.id}
+        id={path.join(TREEGRID_PATH_SEPARATOR)}
+        classNames='grid grid-cols-subgrid col-span-full items-center py-1'
+        {...(parentOf && { parentOf: parentOf.join(TREEGRID_PARENT_OF_SEPARATOR) })}
+      >
+        <Treegrid.Cell indent classNames='flex items-center gap-1'>
+          {node.icon && <Icon icon={node.icon} classNames='w-[1em] h-[1em]' />}
+          {node.title}
+        </Treegrid.Cell>
+        <Treegrid.Cell classNames='text-end text-description tabular-nums'>{node.nodes?.length ?? 0}</Treegrid.Cell>
+      </Treegrid.Row>
+    ))}
+  </Treegrid.Root>
+);
+
+const meta = {
+  title: 'ui/react-ui-list/Treegrid',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/components/Treegrid/Treegrid.theme.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { tv } from '@dxos/ui-theme';
+
+// Per-level indentation of the first `.indent` cell, plus a bolder root row. Clamped to 1–8.
+const levelStyles = new Map<number, string>([
+  [1, '[&>.indent:first-of-type]:pl-0 font-medium'],
+  [2, '[&>.indent:first-of-type]:pl-0'],
+  [3, '[&>.indent:first-of-type]:pl-1'],
+  [4, '[&>.indent:first-of-type]:pl-2'],
+  [5, '[&>.indent:first-of-type]:pl-3'],
+  [6, '[&>.indent:first-of-type]:pl-4'],
+  [7, '[&>.indent:first-of-type]:pl-5'],
+  [8, '[&>.indent:first-of-type]:pl-6'],
+]);
+
+const treegridStyles = tv({
+  slots: {
+    root: 'grid',
+    row: '',
+    cell: '',
+  },
+  variants: {
+    // `indent` marks the cell that carries the per-level left padding (selected via `.indent`).
+    indent: {
+      true: { cell: 'indent' },
+    },
+  },
+});
+
+/** Self-contained {@link Treegrid} theme (tailwind-variants), plus the level→row-class lookup. */
+export const treegridTheme = {
+  styles: treegridStyles,
+  /** Row class for a 1-based depth level (clamped to 1–8). */
+  rowLevel: (level: number): string => levelStyles.get(Math.min(Math.max(Math.round(level), 1), 8)) ?? '',
+};

package/src/components/Treegrid/Treegrid.tsx

@@ -0,0 +1,187 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useFocusFinders } from '@fluentui/react-tabster';
+import { type Scope, createContextScope } from '@radix-ui/react-context';
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import { useControllableState } from '@radix-ui/react-use-controllable-state';
+import React, {
+  type ComponentPropsWithRef,
+  type CSSProperties,
+  type KeyboardEvent,
+  forwardRef,
+  useCallback,
+} from 'react';
+
+import { type ThemedClassName, composable, composableProps } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { treegridTheme } from './Treegrid.theme';
+
+// TODO(thure): https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/treegrid_role
+
+const styles = treegridTheme.styles();
+
+const TREEGRID_ROW_NAME = 'Treegrid.Row';
+
+type TreegridRowScopedProps<P> = P & { __treegridRowScope?: Scope };
+
+const [createTreegridRowContext, createTreegridRowScope] = createContextScope(TREEGRID_ROW_NAME, []);
+
+type TreegridRowContextValue = {
+  open?: boolean;
+  onOpenChange?: (nextOpen: boolean) => void;
+};
+
+const [TreegridRowProvider, useTreegridRowContext] =
+  createTreegridRowContext<TreegridRowContextValue>(TREEGRID_ROW_NAME);
+
+// TODO(burdon): Replace with functions.
+export const TREEGRID_PATH_SEPARATOR = '~';
+export const TREEGRID_PARENT_OF_SEPARATOR = ' ';
+
+type TreegridRootProps = ThemedClassName<ComponentPropsWithRef<typeof Primitive.div>> & {
+  gridTemplateColumns?: CSSProperties['gridTemplateColumns'];
+  asChild?: boolean;
+};
+
+const TreegridRoot = composable<HTMLDivElement, TreegridRootProps>(
+  ({ asChild, classNames, children, style, gridTemplateColumns, onKeyDown: onKeyDownProp, ...props }, forwardedRef) => {
+    const { className, role: _role, ...rest } = composableProps<HTMLDivElement>(props, { classNames });
+    const Comp = asChild ? Slot : Primitive.div;
+    const { findFirstFocusable } = useFocusFinders();
+
+    const handleKeyDown = useCallback(
+      (event: KeyboardEvent<HTMLDivElement>) => {
+        switch (event.key) {
+          case 'ArrowDown':
+          case 'ArrowUp': {
+            const direction = event.key === 'ArrowDown' ? 'down' : 'up';
+            const target = event.target as HTMLElement;
+
+            // Find ancestor with data-arrow-keys containing the relevant direction.
+            const ancestorWithArrowKeys = target.closest(`[data-arrow-keys*="${direction}"], [data-arrow-keys="all"]`);
+
+            // If no ancestor with data-arrow-keys found, proceed with row navigation.
+            if (!ancestorWithArrowKeys) {
+              // Find the closest row
+              const currentRow = target.closest('[role="row"]');
+              if (currentRow) {
+                // Find the treegrid container.
+                const treegrid = currentRow.closest('[role="treegrid"]');
+                if (treegrid) {
+                  // Get all rows in the treegrid.
+                  const rows = Array.from(treegrid.querySelectorAll('[role="row"]'));
+                  const currentIndex = rows.indexOf(currentRow as Element);
+
+                  // Find next or previous row.
+                  const nextIndex = direction === 'down' ? currentIndex + 1 : currentIndex - 1;
+                  const targetRow = rows[nextIndex];
+
+                  if (targetRow) {
+                    // Focus the first focusable element in the target row.
+                    const firstFocusable = findFirstFocusable(targetRow as HTMLElement);
+                    if (firstFocusable) {
+                      event.preventDefault();
+                      firstFocusable.focus();
+                    }
+                  }
+                }
+              }
+            }
+            break;
+          }
+        }
+        onKeyDownProp?.(event);
+      },
+      [findFirstFocusable, onKeyDownProp],
+    );
+
+    return (
+      <Comp
+        role='treegrid'
+        {...rest}
+        className={styles.root({ class: mx(className) })}
+        style={{ ...style, gridTemplateColumns }}
+        onKeyDown={handleKeyDown}
+        ref={forwardedRef}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+type TreegridRowProps = ThemedClassName<ComponentPropsWithRef<typeof Primitive.div>> & {
+  id: string;
+  asChild?: boolean;
+  parentOf?: string;
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?(open: boolean): void;
+};
+
+const TreegridRow = forwardRef<HTMLDivElement, TreegridRowScopedProps<TreegridRowProps>>(
+  (
+    {
+      __treegridRowScope,
+      asChild,
+      classNames,
+      children,
+      id,
+      parentOf,
+      open: propsOpen,
+      defaultOpen,
+      onOpenChange: propsOnOpenChange,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    const Comp = asChild ? Slot : Primitive.div;
+    const pathParts = id.split(TREEGRID_PATH_SEPARATOR);
+    const level = pathParts.length - 1;
+    const [open, onOpenChange] = useControllableState({
+      prop: propsOpen,
+      onChange: propsOnOpenChange,
+      defaultProp: defaultOpen,
+    });
+
+    return (
+      <TreegridRowProvider open={open} onOpenChange={onOpenChange} scope={__treegridRowScope}>
+        <Comp
+          role='row'
+          aria-level={level}
+          className={styles.row({ class: mx(treegridTheme.rowLevel(level), classNames) })}
+          {...(parentOf && { 'aria-expanded': open, 'aria-owns': parentOf })}
+          {...props}
+          id={id}
+          ref={forwardedRef}
+        >
+          {children}
+        </Comp>
+      </TreegridRowProvider>
+    );
+  },
+);
+
+type TreegridCellProps = ThemedClassName<ComponentPropsWithRef<typeof Primitive.div>> & { indent?: boolean };
+
+const TreegridCell = forwardRef<HTMLDivElement, TreegridCellProps>(
+  ({ classNames, children, indent, ...props }, forwardedRef) => {
+    return (
+      <div role='gridcell' className={styles.cell({ indent, class: mx(classNames) })} {...props} ref={forwardedRef}>
+        {children}
+      </div>
+    );
+  },
+);
+
+export type { TreegridRootProps, TreegridRowProps };
+
+export const Treegrid = {
+  Root: TreegridRoot,
+  Row: TreegridRow,
+  Cell: TreegridCell,
+};

package/src/components/Treegrid/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './Treegrid';

package/src/components/index.ts

@@ -4,7 +4,10 @@
 
 export * from './Accordion';
 export * from './Combobox';
+export * from './DropIndicator';
+export * from './Empty';
 export * from './Listbox';
 export * from './OrderedList';
 export * from './Picker';
 export * from './Tree';
+export * from './Treegrid';