@mich8060/unified-design-system 0.1.10

package/src/ui/Accordion/Accordion.ai.md

@@ -0,0 +1,69 @@
+# Accordion
+
+Expandable/collapsible content sections for organizing information hierarchically.
+
+## When to Use
+- FAQs, settings panels, or grouped content that benefits from progressive disclosure
+- Reducing visual clutter by hiding secondary information behind headers
+
+## Props
+
+### Accordion (container)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | `AccordionItem` components |
+| `className` | `string` | `""` | Additional CSS classes |
+
+### AccordionItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Header text for the item |
+| `defaultExpanded` | `boolean` | `false` | Whether item starts expanded |
+| `children` | `ReactNode` | — | Content shown when expanded |
+| `className` | `string` | `""` | Additional CSS classes |
+| `onToggle` | `function` | — | Callback `(isExpanded: boolean) => void` |
+
+## Examples
+
+### Basic accordion
+```jsx
+<Accordion>
+  <AccordionItem label="Section 1">
+    <p>Content for section 1</p>
+  </AccordionItem>
+  <AccordionItem label="Section 2">
+    <p>Content for section 2</p>
+  </AccordionItem>
+  <AccordionItem label="Section 3" defaultExpanded>
+    <p>This section starts expanded</p>
+  </AccordionItem>
+</Accordion>
+```
+
+### FAQ pattern
+```jsx
+<Accordion>
+  {faqs.map((faq) => (
+    <AccordionItem key={faq.id} label={faq.question}>
+      <p>{faq.answer}</p>
+    </AccordionItem>
+  ))}
+</Accordion>
+```
+
+## Import
+```jsx
+import { Accordion, AccordionItem } from "@mich8060/chg-design-system";
+// OR
+import Accordion, { AccordionItem } from "@mich8060/chg-design-system/Accordion";
+```
+
+## Do's and Don'ts
+
+✅ **Do**: Use for content that doesn't all need to be visible at once
+✅ **Do**: Use `defaultExpanded` on the most important section
+
+❌ **Don't**: Nest accordions inside accordions
+❌ **Don't**: Put critical information only inside accordion items

package/src/ui/Accordion/Accordion.scss

@@ -0,0 +1,87 @@
+@use "../../styles/typography" as *;
+
+.accordion {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+
+  // ── Block: accordion-item ───────────────────────────
+  &-item {
+    display: flex;
+    flex-direction: column;
+    border-bottom: var(--uds-border-width-1) solid var(--uds-border-primary);
+    width: 100%;
+
+    &:last-child {
+      border-bottom: none;
+    }
+
+    // ── Element: header button ──────────────────────────
+    &__header {
+      @include uds-body-16-semibold;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--uds-gap-16);
+      padding: var(--uds-spacing-12) var(--uds-spacing-16);
+      background: var(--uds-surface-primary);
+      border: none;
+      cursor: pointer;
+      width: 100%;
+      text-align: left;
+      color: var(--uds-text-primary);
+      transition: background-color 0.3s ease;
+
+      &:hover {
+        background-color: var(--uds-surface-tertiary);
+      }
+
+      &:focus-visible {
+        outline: solid var(--uds-focus-ring-width) var(--uds-focus-ring-border);
+        outline-offset: var(--uds-focus-ring-offset);
+      }
+    }
+
+    // ── Element: label text ─────────────────────────────
+    &__label {
+      flex: 1;
+      line-height: 24px;
+    }
+
+    // ── Element: chevron icon ───────────────────────────
+    &__icon {
+      flex-shrink: 0;
+      transition: transform 0.3s ease;
+      color: var(--uds-text-primary);
+
+      &--expanded {
+        transform: rotate(180deg);
+      }
+    }
+
+    // ── Element: collapsible body ───────────────────────
+    &__body {
+      display: grid;
+      grid-template-rows: 0fr;
+      opacity: 0;
+      transition:
+        grid-template-rows 0.3s ease,
+        opacity 0.2s ease;
+
+      &--expanded {
+        grid-template-rows: 1fr;
+        opacity: 1;
+
+        .accordion-item__body-inner {
+          padding-bottom: var(--uds-spacing-24);
+        }
+      }
+
+      &-inner {
+        overflow: hidden;
+        padding: 0 var(--uds-spacing-16);
+        transition: padding 0.2s ease;
+      }
+    }
+  }
+}

package/src/ui/Accordion/Accordion.spec.ts

@@ -0,0 +1,25 @@
+export const ACCORDION_BASE_CLASS = "accordion";
+export const ACCORDION_ITEM_BASE_CLASS = "accordion-item";
+
+export const ACCORDION_DEFAULTS = {
+  className: "",
+} as const;
+
+export const ACCORDION_ITEM_DEFAULTS = {
+  defaultExpanded: false,
+  className: "",
+} as const;
+
+export const ACCORDION_STORY_SPEC = {
+  defaults: {
+    expandedFirst: false as boolean,
+  },
+  stories: {
+    default: { expandedFirst: false },
+    firstExpanded: { expandedFirst: true },
+  },
+  items: [
+    { id: "section-one", label: "Section One", content: "First section content" },
+    { id: "section-two", label: "Section Two", content: "Second section content" },
+  ],
+} as const;

package/src/ui/Accordion/Accordion.stories.tsx

@@ -0,0 +1,46 @@
+import Accordion, { AccordionItem } from "./Accordion";
+import { ACCORDION_STORY_SPEC } from "./Accordion.spec";
+import { createStoryArgsFromSpec } from "../_spec/createStoryArgsFromSpec";
+
+const fromSpec = createStoryArgsFromSpec(ACCORDION_STORY_SPEC.defaults);
+
+export default {
+  title: "Components/Accordion",
+  component: Accordion,
+  tags: ["autodocs"],
+  args: ACCORDION_STORY_SPEC.defaults,
+  parameters: {},
+  argTypes: {
+    expandedFirst: {
+      control: "boolean",
+      description: "Expands the first accordion item by default.",
+    },
+  },
+};
+
+const renderFromSpec = (expandedFirst: boolean) => (
+  <Accordion>
+    {ACCORDION_STORY_SPEC.items.map((item, index) => (
+      <AccordionItem
+        key={item.id}
+        id={item.id}
+        label={item.label}
+        defaultExpanded={expandedFirst && index === 0}
+      >
+        {item.content}
+      </AccordionItem>
+    ))}
+  </Accordion>
+);
+
+export const Default = {
+  args: fromSpec(ACCORDION_STORY_SPEC.stories.default),
+  render: ({ expandedFirst }: { expandedFirst: boolean }) =>
+    renderFromSpec(expandedFirst),
+};
+
+export const FirstExpanded = {
+  args: fromSpec(ACCORDION_STORY_SPEC.stories.firstExpanded),
+  render: ({ expandedFirst }: { expandedFirst: boolean }) =>
+    renderFromSpec(expandedFirst),
+};

package/src/ui/Accordion/Accordion.test.tsx

@@ -0,0 +1,54 @@
+import { describe, test } from "@jest/globals";
+import { fireEvent, render, screen } from "@testing-library/react";
+import Accordion, { AccordionItem } from "./Accordion";
+import { ACCORDION_STORY_SPEC } from "./Accordion.spec";
+
+describe("Accordion spec sync", () => {
+  test("renders all spec items", () => {
+    render(
+      <Accordion>
+        {ACCORDION_STORY_SPEC.items.map((item) => (
+          <AccordionItem key={item.id} id={item.id} label={item.label}>
+            {item.content}
+          </AccordionItem>
+        ))}
+      </Accordion>,
+    );
+
+    ACCORDION_STORY_SPEC.items.forEach((item) => {
+      expect(screen.getByRole("button", { name: item.label })).toBeInTheDocument();
+    });
+  });
+
+  test("toggles expanded state on click", () => {
+    render(
+      <Accordion>
+        <AccordionItem id="accordion-test" label="Toggle Section">
+          Body content
+        </AccordionItem>
+      </Accordion>,
+    );
+
+    const trigger = screen.getByRole("button", { name: "Toggle Section" });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  test("honors defaultExpanded", () => {
+    render(
+      <Accordion>
+        <AccordionItem id="accordion-expanded" label="Expanded Section" defaultExpanded>
+          Expanded body
+        </AccordionItem>
+      </Accordion>,
+    );
+
+    const trigger = screen.getByRole("button", { name: "Expanded Section" });
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+  });
+});

package/src/ui/Accordion/Accordion.tsx

@@ -0,0 +1,73 @@
+import { useState } from "react";
+import Icon from "../Icon/Icon";
+import "./Accordion.scss";
+import {
+  ACCORDION_BASE_CLASS,
+  ACCORDION_DEFAULTS,
+  ACCORDION_ITEM_BASE_CLASS,
+  ACCORDION_ITEM_DEFAULTS,
+} from "./Accordion.spec";
+import type { AccordionItemProps, AccordionProps } from "./Accordion.types";
+
+const IconComponent = Icon as any;
+
+export function AccordionItem({
+  label,
+  defaultExpanded = ACCORDION_ITEM_DEFAULTS.defaultExpanded,
+  children,
+  className = ACCORDION_ITEM_DEFAULTS.className,
+  onToggle,
+  id,
+  ...rest
+}: AccordionItemProps) {
+  const [expanded, setExpanded] = useState(defaultExpanded);
+  const contentId = `accordion-content-${id || label}`;
+
+  const handleToggle = () => {
+    const newExpanded = !expanded;
+    setExpanded(newExpanded);
+    onToggle?.(newExpanded);
+  };
+
+  return (
+    <div className={`${ACCORDION_ITEM_BASE_CLASS} ${className}`.trim()} id={id} {...rest}>
+      <button
+        type="button"
+        className={`${ACCORDION_ITEM_BASE_CLASS}__header`}
+        onClick={handleToggle}
+        aria-expanded={expanded}
+        aria-controls={contentId}
+      >
+        <span className={`${ACCORDION_ITEM_BASE_CLASS}__label`}>{label}</span>
+        <IconComponent
+          name="CaretDown"
+          size={16}
+          appearance="bold"
+          className={`${ACCORDION_ITEM_BASE_CLASS}__icon ${
+            expanded ? `${ACCORDION_ITEM_BASE_CLASS}__icon--expanded` : ""
+          }`}
+        />
+      </button>
+      <div
+        id={contentId}
+        className={`${ACCORDION_ITEM_BASE_CLASS}__body ${
+          expanded ? `${ACCORDION_ITEM_BASE_CLASS}__body--expanded` : ""
+        }`}
+      >
+        <div className={`${ACCORDION_ITEM_BASE_CLASS}__body-inner`}>{children}</div>
+      </div>
+    </div>
+  );
+}
+
+export default function Accordion({
+  children,
+  className = ACCORDION_DEFAULTS.className,
+  ...rest
+}: AccordionProps) {
+  return (
+    <div className={`${ACCORDION_BASE_CLASS} ${className}`.trim()} {...rest}>
+      {children}
+    </div>
+  );
+}

package/src/ui/Accordion/Accordion.types.ts

@@ -0,0 +1,15 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+export interface AccordionProps extends HTMLAttributes<HTMLDivElement> {
+  children?: ReactNode;
+  className?: string;
+}
+
+export interface AccordionItemProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "onToggle"> {
+  label: string;
+  defaultExpanded?: boolean;
+  children?: ReactNode;
+  className?: string;
+  onToggle?: (expanded: boolean) => void;
+}

package/src/ui/Accordion/index.js

@@ -0,0 +1 @@
+export { default, AccordionItem } from "./Accordion";

package/src/ui/ActionMenu/ActionMenu.ai.md

@@ -0,0 +1,106 @@
+# ActionMenu
+
+Contextual dropdown menu triggered by a button, for grouping actions. Also used internally by the `Dropdown` component for its options popover.
+
+## When to Use
+- "More actions" menus on cards, table rows, or list items
+- Context menus with multiple actions
+- Overflow menus in toolbars
+- As the internal popup engine inside `Dropdown` (automatically — you don't compose it manually)
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `trigger` | `ReactNode` | — | Element that opens the menu (usually a Button) |
+| `items` | `array` | `[]` | Menu items (see Item Object) |
+| `placement` | `string` | `"bottom-end"` | Menu placement: `"bottom-start"`, `"bottom-end"`, `"top-start"`, `"top-end"` |
+| `fullWidth` | `boolean` | `false` | When `true`, menu stretches to match the trigger width |
+| `disabled` | `boolean` | `false` | Whether the menu is disabled |
+| `onOpenChange` | `function` | — | Callback when open state changes: `(isOpen: boolean) => void` |
+| `className` | `string` | `""` | Additional CSS classes on the root wrapper |
+| `menuClassName` | `string` | `""` | Additional CSS classes on the menu panel |
+
+### Item Object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `label` | `string` | Item text |
+| `icon` | `string` | Phosphor icon name |
+| `onClick` | `function` | Click handler |
+| `shortcut` | `string` | Keyboard shortcut label (rendered with `Key` component) |
+| `active` | `boolean` | Active/selected state |
+| `destructive` | `boolean` | Destructive/danger styling |
+| `disabled` | `boolean` | Disabled state |
+| `divider` | `boolean` | Render as divider instead of item |
+| `items` | `array` | Nested submenu items |
+
+## Examples
+
+### Basic action menu
+```jsx
+<ActionMenu
+  trigger={<Button layout="icon-only" icon="DotsThree" appearance="ghost" />}
+  items={[
+    { label: "Edit", icon: "PencilSimple", onClick: handleEdit },
+    { label: "Duplicate", icon: "Copy", onClick: handleDuplicate },
+    { divider: true },
+    { label: "Delete", icon: "Trash", destructive: true, onClick: handleDelete },
+  ]}
+/>
+```
+
+### Full-width menu
+```jsx
+<ActionMenu
+  trigger={<Button>Choose Action</Button>}
+  items={actions}
+  fullWidth
+  placement="bottom-start"
+/>
+```
+
+### Listening to open/close
+```jsx
+<ActionMenu
+  trigger={<Button icon="Gear">Settings</Button>}
+  items={settingsItems}
+  onOpenChange={(isOpen) => console.log("Menu open:", isOpen)}
+/>
+```
+
+### In a table row
+```jsx
+const columns = [
+  // ...other columns
+  {
+    key: "actions",
+    label: "",
+    render: (_, row) => (
+      <ActionMenu
+        trigger={<Button layout="icon-only" icon="DotsThree" appearance="ghost" size="small" />}
+        items={[
+          { label: "View", onClick: () => navigate(`/items/${row.id}`) },
+          { label: "Edit", onClick: () => openEdit(row) },
+          { divider: true },
+          { label: "Delete", destructive: true, onClick: () => deleteItem(row.id) },
+        ]}
+        placement="bottom-end"
+      />
+    ),
+  },
+];
+```
+
+## Architecture Note
+
+The `Dropdown` component composes ActionMenu internally — it maps its `options` into ActionMenu `items` and passes its select-style trigger button as ActionMenu's `trigger`. This means both components share a single popup engine for click-outside, keyboard navigation, and focus management, while remaining fully independent for consumers.
+
+## Do's and Don'ts
+
+✅ **Do**: Use a `Button` as the trigger element
+✅ **Do**: Use `fullWidth` + `placement="bottom-start"` when the menu should match the trigger width
+✅ **Do**: Use `onOpenChange` when you need to react to open/close state externally
+
+❌ **Don't**: Use ActionMenu for value selection in forms — use `Dropdown` instead
+❌ **Don't**: Add both `disabled` prop and disable the trigger — just use ActionMenu's `disabled`