@pnx-mixtape/mxds 0.1.0-rc.4 → 0.1.0-rc.6

package/docs/API.md

@@ -0,0 +1,1215 @@
+# API Documentation
+
+Reference documentation for utilities and helper functions in the Mixtape Design System.
+
+## Table of Contents
+
+- [Validators](#validators)
+- [Utilities](#utilities)
+- [Helper Classes](#helper-classes)
+- [Hooks](#hooks)
+- [Elements](#elements)
+- [React Components](#react-components)
+- [Design Tokens](#design-tokens)
+- [Enums](#enums)
+- [Global Variables](#global-variables)
+
+---
+
+## Validators
+
+> Located in: `src/Utility/utilities.ts`
+
+The `validators` object provides type-safe input validation without external dependencies.
+
+### Import
+
+```typescript
+import { validators } from "@pnx-mixtape/mxds/src/Utility/utilities"
+```
+
+### validators.url()
+
+Validates a URL string and checks protocol.
+
+```typescript
+validators.url(value: string, allowedProtocols?: string[]): boolean
+```
+
+**Parameters:**
+
+- `value` - URL string to validate
+- `allowedProtocols` - Array of allowed protocols (default: `['http:', 'https:']`)
+
+**Returns:** `true` if valid URL with allowed protocol
+
+**Examples:**
+
+```typescript
+validators.url("https://example.com") // true
+validators.url("http://example.com") // true
+validators.url("javascript:alert(1)") // false
+validators.url("ftp://example.com") // false
+validators.url("ftp://example.com", ["ftp:", "ftps:"]) // true
+```
+
+---
+
+### validators.email()
+
+Validates email address format.
+
+```typescript
+validators.email(value: string): boolean
+```
+
+**Parameters:**
+
+- `value` - Email string to validate
+
+**Returns:** `true` if valid email format
+
+**Examples:**
+
+```typescript
+validators.email("user@example.com") // true
+validators.email("invalid-email") // false
+validators.email("user@domain") // false
+```
+
+---
+
+### validators.number()
+
+Validates a number with optional min/max bounds.
+
+```typescript
+validators.number(value: any, min?: number, max?: number): boolean
+```
+
+**Parameters:**
+
+- `value` - Value to validate as number
+- `min` - Optional minimum value (inclusive)
+- `max` - Optional maximum value (inclusive)
+
+**Returns:** `true` if valid number within bounds
+
+**Examples:**
+
+```typescript
+validators.number(5) // true
+validators.number("5") // true (converts)
+validators.number(5, 1, 10) // true
+validators.number(15, 1, 10) // false
+validators.number("abc") // false
+```
+
+---
+
+### validators.integer()
+
+Validates an integer with optional min/max bounds.
+
+```typescript
+validators.integer(value: any, min?: number, max?: number): boolean
+```
+
+**Parameters:**
+
+- `value` - Value to validate as integer
+- `min` - Optional minimum value (inclusive)
+- `max` - Optional maximum value (inclusive)
+
+**Returns:** `true` if valid integer within bounds
+
+**Examples:**
+
+```typescript
+validators.integer(5, 1, 10) // true
+validators.integer(5.5, 1, 10) // false (not integer)
+validators.integer(-1, 1, 10) // false (below min)
+validators.integer("5", 1, 10) // true (converts)
+```
+
+---
+
+### validators.string()
+
+Validates a string with optional length constraints.
+
+```typescript
+validators.string(value: any, minLength?: number, maxLength?: number): boolean
+```
+
+**Parameters:**
+
+- `value` - Value to validate as string
+- `minLength` - Optional minimum length
+- `maxLength` - Optional maximum length
+
+**Returns:** `true` if valid string within length bounds
+
+**Examples:**
+
+```typescript
+validators.string("hello", 1, 10) // true
+validators.string("", 1, 10) // false
+validators.string("toolongstring", 1, 5) // false
+```
+
+---
+
+### validators.notEmpty()
+
+Validates a string is not empty (after trimming).
+
+```typescript
+validators.notEmpty(value: string): boolean
+```
+
+**Parameters:**
+
+- `value` - String to validate
+
+**Returns:** `true` if string has content after trimming
+
+**Examples:**
+
+```typescript
+validators.notEmpty("hello") // true
+validators.notEmpty("   ") // false
+validators.notEmpty("") // false
+```
+
+---
+
+### validators.pattern()
+
+Validates a value matches a regex pattern.
+
+```typescript
+validators.pattern(value: string, pattern: RegExp): boolean
+```
+
+**Parameters:**
+
+- `value` - String to validate
+- `pattern` - Regex pattern to match
+
+**Returns:** `true` if value matches pattern
+
+**Examples:**
+
+```typescript
+validators.pattern("abc123", /^[a-z0-9]+$/) // true
+validators.pattern("ABC", /^[a-z]+$/) // false
+validators.pattern("test@example.com", /^[\w.]+@[\w.]+$/) // true
+```
+
+---
+
+### validators.oneOf()
+
+Validates a value is one of the allowed values.
+
+```typescript
+validators.oneOf<T>(value: T, allowedValues: T[]): boolean
+```
+
+**Parameters:**
+
+- `value` - Value to check
+- `allowedValues` - Array of allowed values
+
+**Returns:** `true` if value is in allowed list
+
+**Examples:**
+
+```typescript
+validators.oneOf("red", ["red", "green", "blue"]) // true
+validators.oneOf("yellow", ["red", "green", "blue"]) // false
+validators.oneOf(5, [1, 5, 10]) // true
+```
+
+---
+
+### validators.array()
+
+Validates an array with optional length constraints.
+
+```typescript
+validators.array(value: any, minLength?: number, maxLength?: number): boolean
+```
+
+**Parameters:**
+
+- `value` - Value to validate as array
+- `minLength` - Optional minimum array length
+- `maxLength` - Optional maximum array length
+
+**Returns:** `true` if valid array within length bounds
+
+**Examples:**
+
+```typescript
+validators.array([1, 2, 3], 1, 5) // true
+validators.array([], 1, 5) // false
+validators.array([1, 2, 3], 5, 10) // false
+```
+
+---
+
+### validators.json()
+
+Validates a value is a valid JSON string.
+
+```typescript
+validators.json(value: string): boolean
+```
+
+**Parameters:**
+
+- `value` - String to validate as JSON
+
+**Returns:** `true` if valid JSON string
+
+**Examples:**
+
+```typescript
+validators.json('{"key": "value"}') // true
+validators.json("invalid{json") // false
+validators.json("[1, 2, 3]") // true
+```
+
+---
+
+### validators.date()
+
+Validates a date string or Date object.
+
+```typescript
+validators.date(value: string | Date, minDate?: Date, maxDate?: Date): boolean
+```
+
+**Parameters:**
+
+- `value` - Date string or Date object to validate
+- `minDate` - Optional minimum date
+- `maxDate` - Optional maximum date
+
+**Returns:** `true` if valid date within bounds
+
+**Examples:**
+
+```typescript
+validators.date("2024-01-01") // true
+validators.date("invalid-date") // false
+validators.date(new Date()) // true
+validators.date("2024-06-15", new Date("2024-01-01"), new Date("2024-12-31")) // true
+```
+
+---
+
+### validators.hexColor()
+
+Validates a hex color code.
+
+```typescript
+validators.hexColor(value: string): boolean
+```
+
+**Parameters:**
+
+- `value` - Color string to validate
+
+**Returns:** `true` if valid hex color (3 or 6 digits)
+
+**Examples:**
+
+```typescript
+validators.hexColor("#fff") // true
+validators.hexColor("#ffffff") // true
+validators.hexColor("#FF0000") // true
+validators.hexColor("fff") // false (missing #)
+validators.hexColor("#gggggg") // false (invalid hex)
+```
+
+---
+
+## Utilities
+
+### makeAnchor()
+
+Converts a string to a valid HTML ID.
+
+```typescript
+makeAnchor(string: string, length?: number): string
+```
+
+**Parameters:**
+
+- `string` - String to convert
+- `length` - Maximum length (default: 20)
+
+**Returns:** Valid HTML ID string
+
+**Examples:**
+
+```typescript
+makeAnchor("Hello World") // 'hello-world'
+makeAnchor("Hello World", 5) // 'hello'
+makeAnchor("Test 123!") // 'test-123'
+makeAnchor("  spaces  ") // 'spaces'
+```
+
+---
+
+### makeCamelCase()
+
+Converts a string to camelCase.
+
+```typescript
+makeCamelCase(string: string): string
+```
+
+**Parameters:**
+
+- `string` - String to convert
+
+**Returns:** camelCase string
+
+**Examples:**
+
+```typescript
+makeCamelCase("hello world") // 'helloWorld'
+makeCamelCase("Hello World") // 'helloWorld'
+makeCamelCase("hello-world") // 'helloWorld'
+```
+
+---
+
+### isInternalLink()
+
+Checks if a URL is internal to the current site.
+
+```typescript
+isInternalLink(href: string, internalHostnames: string[]): boolean
+```
+
+**Parameters:**
+
+- `href` - URL to check
+- `internalHostnames` - Array of internal hostnames
+
+**Returns:** `true` if URL is internal
+
+**Examples:**
+
+```typescript
+isInternalLink("https://example.com/page", ["example.com"]) // true
+isInternalLink("https://other.com/page", ["example.com"]) // false
+```
+
+---
+
+### createElement()
+
+Safely creates an HTML element from a string.
+
+```typescript
+createElement(string: string): Element | null
+```
+
+**Parameters:**
+
+- `string` - HTML string to parse
+
+**Returns:** Parsed Element or null
+
+**Examples:**
+
+```typescript
+const el = createElement('<div class="test">Content</div>')
+// Returns: <div class="test">Content</div>
+
+const unsafe = createElement("<script>alert(1)</script>")
+// Returns: <script> element (but script doesn't execute)
+```
+
+---
+
+### handleOutsideClick()
+
+Handles clicks outside a container.
+
+```typescript
+handleOutsideClick(
+  event: MouseEvent,
+  container: HTMLElement,
+  callback: () => void,
+  ignored?: HTMLElement[]
+): void
+```
+
+**Parameters:**
+
+- `event` - Mouse event
+- `container` - Container element
+- `callback` - Function to call if outside
+- `ignored` - Elements to ignore (optional)
+
+**Examples:**
+
+```typescript
+document.addEventListener('click', (e) => {
+  handleOutsideClick(e, dialog, () => {
+    dialog.close()
+  }, [triggerButton])
+})
+```
+
+---
+
+### handleEscape()
+
+Handles Escape key press.
+
+```typescript
+handleEscape(event: KeyboardEvent, callback: () => void): void
+```
+
+**Parameters:**
+
+- `event` - Keyboard event
+- `callback` - Function to call on Escape
+
+**Examples:**
+
+```typescript
+document.addEventListener("keydown", e => {
+  handleEscape(e, () => {
+    modal.close()
+  })
+})
+```
+
+---
+
+### getElementBox()
+
+Observes an element's dimensions via `ResizeObserver` and writes them as CSS custom properties on the element itself. Useful for container-query-style layouts without native container queries.
+
+```typescript
+getElementBox(element: HTMLElement, once?: boolean, content?: boolean): void
+```
+
+**Parameters:**
+
+- `element` - Element to observe
+- `once` - If `true`, stops observing after the first measurement (default: `false`)
+- `content` - If `true`, measures `contentBoxSize` instead of `borderBoxSize` (default: `false`)
+
+**Sets on the element:**
+
+- `--inline-size` — current inline (horizontal) size in `px`
+- `--block-size` — current block (vertical) size in `px`
+
+**Examples:**
+
+```typescript
+// Continuously track size
+getElementBox(containerEl)
+
+// Measure once (e.g. for initial layout)
+getElementBox(containerEl, true)
+
+// Use in CSS
+// .mx-component { width: calc(var(--inline-size) / 2); }
+```
+
+---
+
+### generatedId()
+
+Generates a stable HTML-safe ID from a Web Component's text content. Used internally by Web Components when an element has no existing `id`.
+
+```typescript
+private generatedId(): string
+```
+
+**Returns:** A kebab-case HTML ID string derived from the component's text content, via `makeAnchor()`.
+
+**Examples:**
+
+```typescript
+// Inside a Web Component:
+details.id = details.id || this.generatedId()
+// If textContent is "My Accordion Section", produces: "my-accordion-section"
+```
+
+**Note:** This is a private method on Web Component classes. It is not exported from the utilities module. Use `makeAnchor()` directly if you need the same behaviour outside a component.
+
+---
+
+## Helper Classes
+
+### DisclosureWidget
+
+Manages disclosure patterns (show/hide content) using an `inert` attribute toggle and `aria-expanded` state.
+
+```typescript
+import { DisclosureWidget } from "@pnx-mixtape/mxds/src/Utility/utilities"
+
+const widget = new DisclosureWidget(trigger, target, options?, context?)
+widget.init()    // Attach and set initial state (idempotent — safe to call multiple times)
+widget.attach()  // Add event listeners
+widget.detach()  // Remove event listeners and close if open
+```
+
+**Constructor:**
+
+```typescript
+new DisclosureWidget(
+  trigger: Element,                  // The button/trigger element
+  element: Element,                  // The content element to show/hide
+  options?: DisclosureWidgetOptions, // Optional overrides (see below)
+  context?: Element | Document,      // Default: document
+)
+```
+
+**Options (`DisclosureWidgetOptions`):**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `attribute` | `string` | `"inert"` | HTML attribute toggled on the target element |
+| `shouldPreventDefault` | `boolean` | `true` | Call `preventDefault()` on trigger events |
+| `setInitialAttribute` | `boolean` | `true` | Set the attribute on init (starts closed) |
+| `clickEvent` | `"click" \| "mouseover"` | `"click"` | Event type to trigger toggle |
+
+**Custom Event — `disclosure-toggle`:**
+
+Dispatched on the trigger element after each toggle:
+
+```typescript
+trigger.addEventListener("disclosure-toggle", (e: CustomEvent<DisclosureWidgetEvent>) => {
+  const { isOpen, id, options, target } = e.detail
+})
+```
+
+```typescript
+type DisclosureWidgetEvent = {
+  isOpen: boolean      // Whether the widget is now open
+  id: string           // ID of the target element
+  options: DisclosureWidgetOptions
+  target: Element      // The content element
+}
+```
+
+**Used in:** Accordion, Tabs, Dialog
+
+---
+
+### Keyboard
+
+Manages keyboard navigation (arrow keys, Escape) for menus and popup overlays. Uses `window.Mixtape` to coordinate state across components — see [Global Variables → Mixtape](#global-variables).
+
+```typescript
+import { Keyboard } from "@pnx-mixtape/mxds/src/Utility/utilities"
+
+const keyboard = new Keyboard()
+
+// Register a popup so Escape closes it
+keyboard.attachPopup(id, closefn)
+keyboard.detachPopup(id)
+
+// Register a menu for arrow-key navigation
+keyboard.attachMenu(container, items)
+keyboard.detachMenu()
+
+// Attach global click + keydown listeners (pass AbortSignal for cleanup)
+keyboard.attachEventListeners(signal)
+```
+
+**Key bindings handled by `attachEventListeners`:**
+
+| Key | Behaviour |
+|---|---|
+| `Escape` | Calls `closefn` on the most recently attached popup |
+| `ArrowDown` / `ArrowRight` | Moves focus forward in attached menu (wraps) |
+| `ArrowUp` / `ArrowLeft` | Moves focus backward in attached menu (wraps) |
+
+**Note:** `attachEventListeners(signal)` must be called after `attachMenu`/`attachPopup`. Pass an `AbortSignal` so listeners are cleaned up automatically.
+
+**Used in:** Navigation, DropMenu, Tabs
+
+---
+
+### CookieCompliance
+
+Manages cookie consent banner. Initialised via the static `create()` factory which uses `window.once` to prevent double-initialisation.
+
+```typescript
+import { CookieCompliance } from "@pnx-mixtape/mxds/src/Utility/utilities"
+
+CookieCompliance.create({ context: document })
+```
+
+After creation, the instance is available at `window.CookieCompliance`. Other scripts can check consent before initialising tracking:
+
+```typescript
+if (window.CookieCompliance?.hasConsent()) {
+  // safe to init analytics
+}
+```
+
+**Required HTML attributes on child elements:**
+
+| Attribute | Element | Purpose |
+|---|---|---|
+| `data-cookie-accept` | `<button>` | Accept button |
+| `data-cookie-reject` | `<button>` | Reject button |
+| `data-cookie-more` | `<button>` | "More info" button |
+| `data-wait-remove` | Banner root | ms delay before banner is removed from DOM |
+
+---
+
+### IntersectionLoader
+
+Lazy-loads a component when its placeholder element scrolls into the viewport.
+
+```typescript
+import { IntersectionLoader } from "@pnx-mixtape/mxds/src/Utility/utilities"
+
+IntersectionLoader.create("[data-lazy]", async () => {
+  const { default: Component } = await import("./Component")
+  // initialise Component
+})
+```
+
+**Required HTML attributes on target elements:**
+
+| Attribute | Purpose |
+|---|---|
+| `data-load-fallback` | Optional `<button>` shown if JS lazy load fails |
+| `data-load-error` | Optional element revealed on load error |
+
+**Note:** `create()` requires `window.once` to be present. In non-Drupal projects, assign [`@drupal/once`](https://www.npmjs.com/package/@drupal/once) to `window.once` at your entry point. Elements are guarded with the `"intersection-loader"` once key.
+
+---
+
+### BreakpointLoader
+
+Lazy-loads a component when a media query matches.
+
+```typescript
+import { BreakpointLoader } from "@pnx-mixtape/mxds/src/Utility/utilities"
+
+BreakpointLoader.create(
+  "[data-responsive]",
+  async () => {
+    const { default: Component } = await import("./Component")
+    // initialise Component
+  },
+  { mediaQuery: "(max-width: 720px)" }, // default if omitted
+)
+```
+
+**Options (`BreakpointLoaderOptions`):**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `mediaQuery` | `string` | `"(max-width: 720px)"` | Standard media query string passed to `window.matchMedia` |
+
+**Required HTML attributes** are the same as `IntersectionLoader` (`data-load-fallback`, `data-load-error`).
+
+**Note:** `create()` requires `window.once` to be present. Elements are guarded with the `"breakpoint-loader"` once key.
+
+---
+
+## Hooks
+
+### useLocalStorage
+
+React hook for localStorage with sync across tabs.
+
+```typescript
+import { useLocalStorage } from "@pnx-mixtape/mxds/src/Utility/Hooks/useLocalStorage"
+
+const [value, setValue] = useLocalStorage({
+  key: "theme",
+  initialValue: "light",
+})
+```
+
+**Features:**
+
+- Syncs across tabs
+- JSON validation
+- Error handling
+- SSR-safe
+
+---
+
+### useUrlParams
+
+React hook for URL parameters management.
+
+```typescript
+import { useUrlParams } from "@pnx-mixtape/mxds/src/Utility/Hooks/useUrlParams"
+
+const { searchParams, pathname, history } = useUrlParams()
+
+// Read param
+const page = searchParams?.get("page")
+
+// Update URL
+history?.pushState(null, "", `${pathname}?page=2`)
+```
+
+---
+
+## Elements
+
+### Web Component Exports
+
+Web Components are exported from `src/elements.ts`:
+
+```typescript
+// Import all Web Components
+import {
+  Accordion,
+  AccordionGroup,
+  AccordionMobile,
+  AccordionDiv,
+  Dialog,
+  DropMenu,
+  ClosableAlert,
+  Sticky,
+  Tabs,
+  GlobalToggle,
+  InPageNavigation,
+  Navigation,
+} from "@pnx-mixtape/mxds"
+```
+
+**Or import individually:**
+
+```typescript
+import Accordion from "@pnx-mixtape/mxds/src/Component/Accordion/Elements/Accordion"
+import Dialog from "@pnx-mixtape/mxds/src/Component/Dialog/Elements/Dialog"
+// ... and so on for each component
+```
+
+**Available Web Components:**
+
+- `Accordion` - Accordion component
+- `AccordionGroup` - Grouped accordions
+- `AccordionMobile` - Mobile accordion variant
+- `AccordionDiv` - Accordion with div wrapper
+- `Dialog` - Modal dialog
+- `DropMenu` - Dropdown menu
+- `ClosableAlert` - Dismissible alert
+- `Sticky` - Sticky positioning
+- `Tabs` - Tab component
+- `GlobalToggle` - Header toggle
+- `InPageNavigation` - In-page navigation
+- `Navigation` - Main navigation
+
+**Utilities also exported:**
+
+The `src/elements.ts` file also re-exports all utilities from `src/Utility/utilities.ts`:
+
+```typescript
+import {
+  // Helper classes
+  DisclosureWidget,
+  Keyboard,
+  CookieCompliance,
+  IntersectionLoader,
+  BreakpointLoader,
+  // Utility functions
+  validators,
+  makeAnchor,
+  makeCamelCase,
+  isInternalLink,
+  createElement,
+  handleOutsideClick,
+  handleEscape,
+} from "@pnx-mixtape/mxds"
+```
+
+---
+
+## React Components
+
+### React Component Exports
+
+React components are exported from `src/react.ts`:
+
+```typescript
+// Import React components
+import {
+  // Atoms
+  Heading,
+  Media,
+  Link,
+  Text,
+  Video,
+  Button,
+  Icon,
+
+  // Components
+  Accordion,
+  AccordionTitle,
+  AccordionTitleIcon,
+  AccordionContent,
+  Breadcrumb,
+  Card,
+  CardContent,
+  CardMedia,
+  ContentBlock,
+  ContentBlockContent,
+  ContentBlockMedia,
+  Dialog,
+  DialogContent,
+  DialogCloseButton,
+  InPageNavigation,
+  InPageAlert,
+  GlobalAlert,
+  HeroBanner,
+  LinkList,
+  LinkListItem,
+  Pagination,
+  PaginationItem,
+  Sticky,
+  Tabs,
+  Tab,
+  TabPanel,
+  TabList,
+  TabDropMenu,
+  Tag,
+  ListItem,
+  ListItemContent,
+  ListItemMedia,
+  Navigation,
+  NavigationDropdown,
+  NavigationDropdownLevel,
+  DropMenu,
+  DropMenuItem,
+  ResultsBar,
+  ResultsBarInfo,
+  ResultsBarSort,
+
+  // Forms
+  FormCheckbox,
+  Checkbox,
+  SingleCheckbox,
+  FormDescription,
+  FormLabel,
+  FormRadio,
+  Radio,
+  FormSelect,
+  Option,
+  FormText,
+  FormTitle,
+  Form,
+
+  // Layout
+  Grid,
+  Page,
+  Section,
+  SectionGrid,
+
+  // Hooks
+  useAccordion,
+  useDialog,
+  useInPageNavigation,
+  usePagination,
+  useTabContext,
+  useDropMenuContext,
+  useLocalStorage,
+  useMediaQuery,
+  useUrlParams,
+
+  // Context Providers
+  ImageComponentProvider,
+  useImageComponent,
+  LinkComponentProvider,
+  useLinkComponent,
+  PaginationProvider,
+  DropMenuProvider,
+} from "@pnx-mixtape/mxds/react"
+```
+
+**Or import individually:**
+
+```typescript
+import Button from "@pnx-mixtape/mxds/src/Atom/Button/Button"
+import Card from "@pnx-mixtape/mxds/src/Component/Card/Card"
+import { useLocalStorage } from "@pnx-mixtape/mxds/react"
+```
+
+---
+
+## Design Tokens
+
+### Accessing Tokens
+
+```javascript
+// In PostCSS config
+import tokens from "@pnx-mixtape/mxds/tokens"
+
+console.log(tokens.colour.brand.primary)
+console.log(tokens.spacing.m)
+console.log(tokens.breakpoint.m)
+```
+
+### Token Structure
+
+```javascript
+tokens = {
+  colour: {
+    text: { primary, secondary, ... },
+    background: { primary, secondary, ... },
+    brand: { primary, secondary, ... },
+  },
+  spacing: { xxs, xs, s, m, l, xl, xxl },
+  font: {
+    size: { ... },
+    family: { ... },
+    weight: { ... },
+  },
+  breakpoint: { xxs, xs, s, m, l, xl },
+  // ... more categories
+}
+```
+
+---
+
+## Related Documentation
+
+- [Code Quality Guidelines](./CodeQuality.md)
+- [Component Architecture](./ComponentArchitecture.md)
+- [Security Guidelines](./Security.md)
+- [Validation Examples](./Security.md#input-validation)
+
+---
+
+## Enums
+
+Enums come from two sources:
+
+- **`src/enums.ts`** — local enums, some of which are migration targets for `@pnx-mixtape/ids-shape`
+- **`@pnx-mixtape/ids-shape`** — the canonical enum package; prefer these going forward
+
+### Migration status
+
+| Local enum | ids-shape equivalent | Status |
+|---|---|---|
+| `AsTags` | `AsTypes` | ⏳ Migrate when reworking JSX components |
+| `FormStatus` | `FormStatusTypes` | ⏳ Migrate when reworking form components |
+| `Alignment` | `MediaAlignmentTypes` | ⏳ Migrate — ids-shape adds `center` value |
+| `TextTags` | — | 🏠 Local only |
+| `HeadingStyles` | — | 🏠 Local only |
+| `TextStyles` | — | 🏠 Local only |
+| `Icons` | — | 🏠 Local only |
+| `PageWidths` | — | 🏠 Local only |
+| `SectionFlow` | — | 🏠 Local only |
+| `SidebarOrder` | — | 🏠 Local only |
+| `BackgroundStyles` | — | 🏠 Local only |
+| `TableStyles` | — | 🏠 Local only |
+| `TabStyles` | — | 🏠 Local only |
+| `SocialShareTypes` | — | 🏠 Local only |
+
+### Also available in ids-shape (not yet used)
+
+These ids-shape enums exist and can replace current string literals in components during the rework:
+
+| ids-shape enum | Purpose |
+|---|---|
+| `ButtonTypes`, `ButtonModifiers` | Button variants and types |
+| `IconColourModifier`, `IconRotateModifier`, `IconSizeModifier` | Icon modifiers |
+| `LoadingTypes` | `lazy` / `eager` image loading |
+| `SectionTypes` | HTML tag selection for sections |
+| `GridModifiers` | Grid column layouts |
+| `TagTypes` | Tag component variants |
+| `InPageAlertTypes`, `GlobalAlertTypes` | Alert type variants |
+| `CardModifier`, `HeroBannerModifier`, `StepsModifier` | Component modifiers |
+| `ListItemModifiers`, `MastheadModifier`, `FooterModifier` | Layout modifiers |
+| `PopoverPlacementModifier` | Popover positioning |
+| `TextModifiers`, `InputTypeTypes` | Text and input variants |
+
+### Importing local enums
+
+```typescript
+import { BackgroundStyles, Icons, TabStyles } from "@pnx-mixtape/mxds/src/enums"
+```
+
+### Importing ids-shape enums
+
+```typescript
+import { AsTypes, FormStatusTypes, ButtonModifiers } from "@pnx-mixtape/ids-shape"
+```
+
+### Local enum values
+
+#### Layout & Structure
+
+| Enum | Values |
+|---|---|
+| `AsTags` | `div`, `li`, `article`, `aside`, `section` |
+| `PageWidths` | `narrow`, `feature`, `full` |
+| `SectionFlow` | `flow`, `group` |
+| `SidebarOrder` | `""` (default), `sidebar-rev`, `sidebar-rev-lg` |
+
+#### Typography
+
+| Enum | Values                                                                                                                                                                                                                                                      |
+|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `TextTags` | `p`, `div`, `strong`, `em`                                                                                                                                                                                                                                  |
+| `HeadingStyles` | `mx-headline`, `mx-text--eyebrow`, `mx-text--embellished`, `mx-text--l`, `mx-heading--xxl`, `mx-heading--xl`, `mx-heading--l`, `mx-heading--m`, `mx-heading--s`, `mx-heading--xs`, `mx-spacing--reset`, `mx-spacing--top-reset`, `mx-spacing--bottom-reset` |
+| `TextStyles` | `mx-headline`, `mx-text--eyebrow`, `mx-text--embellished`, `mx-text--xxl`, `mx-text--xl`, `mx-text--l`, `mx-text--m`, `mx-text--s`, `mx-text--xs`, `mx-text--primary`, `mx-text--accent`                                                                    |
+| `Alignment` | `left`, `right`                                                                                                                                                                                                                                             |
+
+#### Components
+
+| Enum | Values |
+|---|---|
+| `BackgroundStyles` | `primary`, `accent`, `alt`, `reverse`, `reset`, `box` |
+| `TabStyles` | `default`, `centered`, `lined`, `same-height` |
+| `TableStyles` | `flush`, `striped`, `small`, `bordered` |
+
+#### Forms
+
+| Enum | Values |
+|---|---|
+| `FormStatus` | `default`, `valid`, `invalid` |
+
+#### Social & Sharing
+
+| Enum | Values |
+|---|---|
+| `SocialShareTypes` | `twitter`, `facebook`, `linkedin` |
+
+#### Icons
+
+The `Icons` enum maps semantic names to SVG file slugs:
+
+```typescript
+import { Icons } from "@pnx-mixtape/mxds/src/enums"
+// Icons.ARROW_DOWN = "arrow-down"
+// Icons.CLOSE     = "close"
+// Icons.SEARCH    = "search"
+```
+
+| Key | Value | Key | Value |
+|---|---|---|---|
+| `ARROW_DOWN` | `arrow-down` | `ARROW_LEFT` | `arrow-left` |
+| `ARROW_UP` | `arrow-up` | `ARROW_RIGHT` | `arrow-right` |
+| `CHEVRON_DOWN` | `chevron-down` | `CHEVRON_LEFT` | `chevron-left` |
+| `CHEVRON_RIGHT` | `chevron-right` | `CHEVRON_UP` | `chevron-up` |
+| `CLOSE` | `close` | `COLLAPSE` | `collapse` |
+| `DOWNLOAD` | `download` | `DRUPAL` | `drupal` |
+| `ERROR` | `error` | `EXPAND` | `expand` |
+| `EXTERNAL` | `external-link` | `FACEBOOK` | `facebook` |
+| `GOOGLE` | `google` | `INFO` | `info` |
+| `FILE` | `file` | `INSTAGRAM` | `instagram` |
+| `LINKEDIN` | `linkedin` | `MASTODON` | `mastodon` |
+| `MENU` | `menu` | `SEARCH` | `search` |
+| `SUCCESS` | `success` | `TWITTER` | `twitter` |
+| `WARNING` | `warning` | `YOUTUBE` | `youtube` |
+| `EMAIL` | `email` | `HEART` | `heart-selected` |
+| `EMPTY_HEART` | `heart-unselected` | `LINK` | `link` |
+| `LOCK` | `lock` | `LOGIN` | `login` |
+| `MORE` | `more` | `EDIT` | `pencil` |
+| `PHONE` | `phone` | `PIN` | `pin` |
+| `PRINT` | `print` | `RESTART` | `restart` |
+| `STAR` | `star-selected` | `EMPTY_STAR` | `star-unselected` |
+| `TICK` | `tick` | `TRASH` | `trash` |
+| `USER` | `user` | `SHARE` | `share` |
+| `QUESTION` | `question` | | |
+
+---
+
+## Global Variables
+
+These globals are injected by the host environment (Drupal CMS, etc.) and are declared in `.oxlintrc.json` so the linter does not flag them as undefined. They are **not** provided by this design system.
+
+| Global | Type | Source | Purpose |
+|---|---|---|---|
+| `Drupal` | `object` | Drupal CMS | CMS integration — use `loadOnReady()` rather than accessing directly |
+| `once` / `window.once` | `function` | [`@drupal/once`](https://www.npmjs.com/package/@drupal/once) (standalone or Drupal core) | DOM initialisation guard — assign to `window.once` in non-Drupal projects |
+| `Mixtape` | `object` | Internal layer | App-level configuration and feature flags |
+
+### window.once / once
+
+`once()` is a DOM initialisation guard that ensures a selector is only processed once per key, even if the initialisation function is called multiple times. The design system accesses it exclusively via `window.once` and guards every call with `Object.hasOwn(window, "once")`, so **it works with or without Drupal**.
+
+**Standalone usage (non-Drupal projects):**
+
+Install the standalone package:
+
+```bash
+npm install @drupal/once
+```
+
+Then assign it to `window` once at your entry point:
+
+```typescript
+import once from "@drupal/once"
+window.once = once
+```
+
+That's all — `IntersectionLoader`, `BreakpointLoader`, and `CookieCompliance` will all pick it up automatically.
+
+**Inside Drupal:** `once` is already on `window` as part of Drupal core — no setup needed.
+
+**Signature (from `src/Utility/global.d.ts`):**
+
+```typescript
+window.once(name: string, selector: string, context?: any): NodeListOf<HTMLElement>
+```
+
+- Returns a `NodeList` of elements that have **not** already been processed for this `name`.
+- If already processed, returns an empty `NodeList` — preventing double-initialisation.
+- `@see` [npm: @drupal/once](https://www.npmjs.com/package/@drupal/once)
+
+**Example:**
+
+```typescript
+const [el] = window.once("cookie-compliance", "#cookie-compliance", context)
+if (el) {
+  const instance = new CookieCompliance(el)
+  instance.init()
+}
+```
+
+
+### Mixtape
+
+`window.Mixtape` is the internal app-level namespace used by the `Keyboard` class to coordinate menu focus and popup state across components. Its shape is typed in `src/Utility/global.d.ts`:
+
+```typescript
+window.Mixtape = {
+  // Stack of open popups. Keyboard Escape closes the most recent one.
+  Popups: Array<{
+    id: string        // ID of the popup element
+    closefn: () => void  // Function to close it
+  }>,
+
+  // Currently active keyboard-navigable menu.
+  Menu: {
+    context?: HTMLElement  // The menu container
+    items?: NodeListOf<HTMLAnchorElement | HTMLButtonElement>  // Focusable items
+    active?: number        // Index of currently focused item
+  }
+}
+```
+
+Direct use of `window.Mixtape` in component code is rare — use the `Keyboard` class methods (`attachMenu`, `attachPopup`, etc.) which manage this state for you.
+
+### Drupal
+
+The `Drupal` global is provided by Drupal CMS. Direct use of `Drupal.behaviors` in components is rare — use the `loadOnReady()` utility instead, which handles the Drupal/non-Drupal fallback automatically. See the JSDoc on `loadOnReady` in `src/Utility/utilities.ts` for details.
+