@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/DateStrip/DateStrip.tokens.scss

@@ -0,0 +1,23 @@
+// DateStrip.tokens.scss — component tokens. Tile colors default to Button's so
+// theming Button themes the tiles. Convention: --date-strip-<part>-<state>.
+@use '../Button/Button.tokens';
+
+:root {
+  --date-strip-gap: var(--space-2);
+  --date-strip-header-gap: var(--space-3);
+  --date-strip-tile-padding-y: var(--space-2);
+  --date-strip-tile-radius: var(--button-radius);
+  --date-strip-tile-bg: var(--button-bg-secondary);
+  --date-strip-tile-bg-hover: var(--button-bg-secondary-hover);
+  --date-strip-tile-fg: var(--button-fg-secondary);
+  --date-strip-tile-border: var(--button-border-color-secondary);
+  --date-strip-tile-bg-checked: var(--button-bg);
+  --date-strip-tile-bg-checked-hover: var(--button-bg-hover);
+  --date-strip-tile-fg-checked: var(--button-fg);
+  --date-strip-tile-ring: var(--button-ring);
+  --date-strip-tile-opacity-disabled: var(--button-opacity-disabled);
+  --date-strip-dow-font-size: var(--font-size-xs);
+  --date-strip-num-font-size: var(--font-size-lg);
+  --date-strip-num-font-weight: var(--font-weight-semibold);
+  --date-strip-count-font-size: var(--font-size-xs);
+}

package/src/components/DateStrip/DateStrip.tsx

@@ -0,0 +1,205 @@
+import {
+  forwardRef,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type CSSProperties,
+  type FieldsetHTMLAttributes,
+} from 'react';
+import clsx from 'clsx';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+import { Button } from '../Button';
+import { Cluster } from '../Cluster';
+import { Title, type TitleOrder } from '../Title';
+import { LiveRegion } from '../LiveRegion';
+import { VisuallyHidden } from '../VisuallyHidden';
+import { useTranslation } from '../../i18n/useTranslation';
+import { useLocale } from '../../i18n/useLocale';
+import { formatIsoDay, formatIsoRange } from '../_internal/isoDay';
+import styles from './DateStrip.module.scss';
+
+/** One day tile. */
+export interface DateStripDay {
+  /** Calendar day as `'YYYY-MM-DD'`. Formatted in UTC, so the host timezone never shifts it. */
+  date: string;
+  /** Free times that day. `0` renders "No times" and disables the tile. */
+  free: number;
+}
+
+export interface DateStripProps extends Omit<
+  FieldsetHTMLAttributes<HTMLFieldSetElement>,
+  'onChange'
+> {
+  /** The days to show, in order — usually one week (7); one grid column per day. The month heading is derived from the first and last. */
+  days: DateStripDay[];
+  /** Selected day (`'YYYY-MM-DD'`), or `null`. A value not in `days` checks nothing. */
+  value: string | null;
+  /** Called with the chosen day's `'YYYY-MM-DD'`. Controlled — update `value` yourself. */
+  onChange: (date: string) => void;
+  /** Previous-week button handler. Replace `days` with the earlier week. */
+  onPrevious: () => void;
+  /** Next-week button handler. Replace `days` with the later week. */
+  onNext: () => void;
+  /** `false` disables the previous-week button (e.g. the current week). Default `true`. */
+  canPrevious?: boolean;
+  /** `false` disables the next-week button (end of the booking window). Default `true`. */
+  canNext?: boolean;
+  /** Heading level of the month label. Default `2`. */
+  titleOrder?: TitleOrder;
+  /** Radio group `name` (also submitted with a form). Default: a generated id. */
+  name?: string;
+  /** Marks the group `aria-invalid` (the radios themselves do not support it). Field / SettingRow inject it. @default false */
+  invalid?: boolean;
+  /**
+   * Native `required` on the radios (the group then fails form validation
+   * until one is chosen). Field / SettingRow inject it; it used to land on the
+   * root as a stray attribute (#568).
+   */
+  required?: boolean;
+}
+
+/**
+ * One week of selectable day tiles under a month heading with previous/next week buttons.
+ * @see docs/components/DateStrip.md
+ */
+export const DateStrip = forwardRef<HTMLFieldSetElement, DateStripProps>(function DateStrip(
+  {
+    days,
+    value,
+    onChange,
+    onPrevious,
+    onNext,
+    canPrevious = true,
+    canNext = true,
+    titleOrder = 2,
+    name,
+    invalid = false,
+    required = false,
+    className,
+    style,
+    'aria-labelledby': labelledBy,
+    ...props
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const locale = useLocale();
+  const titleId = useId();
+  const generatedName = useId();
+  const groupName = name ?? generatedName;
+
+  const first = days[0]?.date;
+  const last = days[days.length - 1]?.date;
+  const monthLabel =
+    first && last ? formatIsoRange(first, last, locale, { month: 'long', year: 'numeric' }) : '';
+
+  // Rule 10: activating Next keeps focus on the button while the week under
+  // it changes — announce the new range. Computed in an effect keyed on the
+  // first day, so it is silent on mount and on same-week refetches.
+  const [announcement, setAnnouncement] = useState('');
+  const announcedFirst = useRef(first);
+  useEffect(() => {
+    if (first === announcedFirst.current) return;
+    announcedFirst.current = first;
+    setAnnouncement(
+      first && last
+        ? t('dateStrip.range', {
+            range: formatIsoRange(first, last, locale, { month: 'long', day: 'numeric' }),
+          })
+        : '',
+    );
+  }, [first, last, locale, t]);
+
+  return (
+    // {...props} first so the month heading always names the group (Pattern B).
+    // A wrapping Field / SettingRow's label id is MERGED in front of the month
+    // ("Day October 2026"), not replaced — replacing dropped the row label (#568).
+    <fieldset
+      {...props}
+      ref={ref}
+      className={clsx(styles.root, className)}
+      style={{ '--date-strip-columns': Math.max(days.length, 1), ...style } as CSSProperties}
+      aria-label={undefined}
+      aria-labelledby={
+        [labelledBy, monthLabel ? titleId : undefined].filter(Boolean).join(' ') || undefined
+      }
+      aria-invalid={invalid || undefined}
+    >
+      <div className={styles.header}>
+        {monthLabel && (
+          <Title id={titleId} order={titleOrder} size="md">
+            {monthLabel}
+          </Title>
+        )}
+        <Cluster gap="xs">
+          <Button
+            variant="secondary"
+            size="lg"
+            iconOnly
+            aria-label={t('dateStrip.previousWeek')}
+            // aria-disabled, not disabled: pressing Previous on the first
+            // allowed week would otherwise disable the FOCUSED button and drop
+            // focus to <body>.
+            aria-disabled={!canPrevious || undefined}
+            onClick={() => canPrevious && onPrevious()}
+          >
+            <ChevronLeft size={16} aria-hidden="true" />
+          </Button>
+          <Button
+            variant="secondary"
+            size="lg"
+            iconOnly
+            aria-label={t('dateStrip.nextWeek')}
+            aria-disabled={!canNext || undefined}
+            onClick={() => canNext && onNext()}
+          >
+            <ChevronRight size={16} aria-hidden="true" />
+          </Button>
+        </Cluster>
+      </div>
+      <div className={styles.tiles}>
+        {days.map((day) => {
+          const availability =
+            day.free > 0 ? t('dateStrip.free', { count: day.free }) : t('dateStrip.noTimes');
+          return (
+            <label key={day.date} className={styles.tile}>
+              <input
+                type="radio"
+                required={required}
+                className={styles.input}
+                name={groupName}
+                value={day.date}
+                checked={value === day.date}
+                disabled={!(day.free > 0)}
+                onChange={() => onChange(day.date)}
+              />
+              {/* Visual body hidden from AT: its spans would concatenate into
+                  "Wed79 free". The name is the full sentence below. */}
+              <span className={styles.body} aria-hidden="true">
+                <span className={styles.dow}>
+                  {formatIsoDay(day.date, locale, { weekday: 'short' })}
+                </span>
+                <span className={styles.num}>
+                  {formatIsoDay(day.date, locale, { day: 'numeric' })}
+                </span>
+                <span className={styles.count}>{availability}</span>
+              </span>
+              <VisuallyHidden>
+                {t('dateStrip.day', {
+                  date: formatIsoDay(day.date, locale, {
+                    weekday: 'long',
+                    month: 'long',
+                    day: 'numeric',
+                  }),
+                  availability,
+                })}
+              </VisuallyHidden>
+            </label>
+          );
+        })}
+      </div>
+      <LiveRegion>{announcement}</LiveRegion>
+    </fieldset>
+  );
+});

package/src/components/DateStrip/index.ts

@@ -0,0 +1,2 @@
+export { DateStrip } from './DateStrip';
+export type { DateStripProps, DateStripDay } from './DateStrip';

package/src/components/DefinitionList/DefinitionList.module.scss

@@ -0,0 +1,102 @@
+@use '../../styles/mixins' as *;
+@use './DefinitionList.tokens';
+
+.list {
+  // UA reset — <dl> ships with default browser margin we don't want.
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for <dl> default margin
+  margin: 0;
+}
+
+.list[data-layout='horizontal'] {
+  display: grid;
+
+  // minmax(0, …), not plain `1fr` (= minmax(auto, 1fr)): with an `auto` floor
+  // the track can't go below the description's min-content, and a nowrap
+  // child (EntityChip/Text `truncate`) makes that its full one-line width —
+  // the row ran past the card instead of ellipsizing (#580).
+  grid-template-columns: var(--dl-term-width, max-content) minmax(0, 1fr);
+  column-gap: var(--definition-list-column-gap);
+}
+
+.list[data-layout='stacked'] {
+  display: flex;
+  flex-direction: column;
+}
+
+// In horizontal mode the wrapping <div> is a no-op so dt/dd participate
+// in the parent grid directly. In stacked mode it's a normal flex child.
+.list[data-layout='horizontal'] .item {
+  display: contents;
+}
+
+.term,
+.description {
+  // UA reset for <dt>/<dd> default browser styles.
+  // stylelint-disable-next-line property-disallowed-list -- UA reset for <dt>/<dd> defaults
+  margin: 0;
+}
+
+.term {
+  font-size: var(--definition-list-term-font-size);
+  font-weight: var(--definition-list-term-font-weight);
+  color: var(--definition-list-term-fg);
+}
+
+.description {
+  display: flex;
+  align-items: center;
+  gap: var(--definition-list-description-gap);
+  font-size: var(--definition-list-description-font-size);
+  color: var(--definition-list-description-fg);
+
+  // A grid/flex item defaults to `min-width: auto` — its content's min-content
+  // — so the <dd> itself wouldn't shrink into the track either (#580).
+  min-width: 0;
+}
+
+// Horizontal padding matches Card.ListRow's `var(--space-3) var(--space-4)`
+// rhythm so DefinitionList aligns with Card.Header when both sit inside a
+// <Card> (which auto-applies padding="none" once it detects compound children).
+// Outside a Card, this acts as sensible default internal inset.
+.term,
+.description {
+  padding-inline: var(--definition-list-padding-x);
+}
+
+.icon {
+  display: inline-flex;
+  align-items: center;
+  color: var(--definition-list-icon-fg);
+}
+
+// Spacing — padding-block on dt and dd directly. In horizontal mode the
+// .item is display:contents and has no box, so we can't pad it; in stacked
+// mode the same rules still produce the right vertical rhythm.
+.list[data-spacing='sm'] .term,
+.list[data-spacing='sm'] .description {
+  padding-block: var(--definition-list-padding-y-sm);
+}
+
+.list[data-spacing='md'] .term,
+.list[data-spacing='md'] .description {
+  padding-block: var(--definition-list-padding-y-md);
+}
+
+.list[data-spacing='lg'] .term,
+.list[data-spacing='lg'] .description {
+  padding-block: var(--definition-list-padding-y-lg);
+}
+
+// Dividers — in horizontal mode .item is display:contents (no box), so the
+// border goes on every dt/dd after the first row. Using :not(:first-of-type)
+// works because dt and dd are typed elements within the parent dl grid.
+.list[data-dividers='true'][data-layout='horizontal'] .term:not(:first-of-type),
+.list[data-dividers='true'][data-layout='horizontal'] .description:not(:first-of-type) {
+  border-top: var(--border-width) solid var(--definition-list-divider-color);
+}
+
+// In stacked mode the .item HAS a box, so the border goes on each item
+// after the first.
+.list[data-dividers='true'][data-layout='stacked'] .item + .item {
+  border-top: var(--border-width) solid var(--definition-list-divider-color);
+}

package/src/components/DefinitionList/DefinitionList.tokens.scss

@@ -0,0 +1,29 @@
+// DefinitionList.tokens.scss — Component-scoped tokens for <DefinitionList>. Covers the horizontal/stacked layout grid gap, dt/dd typography + insets, icon color, and per-spacing padding-block tokens. Dividers reuse the primitive --border-width (default 1px).
+:root {
+  // Horizontal layout grid gap
+  --definition-list-column-gap: var(--space-4);
+
+  // dt/dd shared inset (matches Card.ListRow rhythm)
+  --definition-list-padding-x: var(--space-4);
+
+  // dt — typography
+  --definition-list-term-font-size: var(--font-size-sm);
+  --definition-list-term-font-weight: var(--font-weight-medium);
+  --definition-list-term-fg: var(--color-fg-muted);
+
+  // dd — typography
+  --definition-list-description-font-size: var(--font-size-sm);
+  --definition-list-description-fg: var(--color-fg);
+  --definition-list-description-gap: var(--space-2);
+
+  // Icon slot inside dd
+  --definition-list-icon-fg: var(--color-fg-subtle);
+
+  // Spacing variants — padding-block per row
+  --definition-list-padding-y-sm: var(--space-2);
+  --definition-list-padding-y-md: var(--space-3);
+  --definition-list-padding-y-lg: var(--space-4);
+
+  // Divider color (between rows when dividers=true)
+  --definition-list-divider-color: var(--color-border);
+}

package/src/components/DefinitionList/DefinitionList.tsx

@@ -0,0 +1,198 @@
+import {
+  Children,
+  Fragment,
+  forwardRef,
+  isValidElement,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import styles from './DefinitionList.module.scss';
+
+/**
+ * Layout direction.
+ * - `'horizontal'` (default) — terms in column 1, descriptions in column 2.
+ *   All rows share a single term column auto-sized to the longest term (or
+ *   `termWidth` if set).
+ * - `'stacked'` — terms stack above descriptions, one per row. Common for
+ *   settings pages and narrow viewports.
+ */
+export type DefinitionListLayout = 'horizontal' | 'stacked';
+
+/**
+ * Vertical padding per item.
+ * - `'sm'` — `var(--space-2)` (default; compact, dense rhythm).
+ * - `'md'` — `var(--space-3)` (roomier; matches Card.ListRow rhythm).
+ * - `'lg'` — `var(--space-4)` (emphasis panels).
+ */
+export type DefinitionListSpacing = 'sm' | 'md' | 'lg';
+
+export interface DefinitionListProps extends HTMLAttributes<HTMLDListElement> {
+  /** Layout direction. See `DefinitionListLayout`. Default `'horizontal'`. */
+  layout?: DefinitionListLayout;
+  /**
+   * CSS length applied to the term column in horizontal layout (e.g. `'180px'`,
+   * `'20%'`, `'max-content'`). Default `'max-content'` — column sizes to the
+   * longest term across all rows. Set explicitly when you need consistent
+   * alignment across multiple DefinitionLists on the same screen.
+   */
+  termWidth?: string;
+  /** Vertical padding per item. See `DefinitionListSpacing`. Default `'sm'`. */
+  spacing?: DefinitionListSpacing;
+  /**
+   * Render a 1px border between items. Default `false` (clean, dense look).
+   * Set when migrating from a `Card.List` and you want to preserve the
+   * table-row separator visual.
+   */
+  dividers?: boolean;
+}
+
+export interface DefinitionListItemProps extends HTMLAttributes<HTMLDivElement> {
+  /** A `DefinitionList.Term` and a `DefinitionList.Description`. */
+  children: ReactNode;
+}
+
+export interface DefinitionListTermProps extends HTMLAttributes<HTMLElement> {
+  /** The label text — kept short, terms are headings for their values. */
+  children: ReactNode;
+}
+
+export interface DefinitionListDescriptionProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Leading decorative icon, rendered inside the `<dd>` before children.
+   * Wrapped in an `aria-hidden` span — the `<dt>` carries the semantic label
+   * so the icon is purely visual.
+   */
+  icon?: ReactNode;
+  /** The value content. Any ReactNode — text, Badges, Links, etc. */
+  children: ReactNode;
+}
+
+/**
+ * Flatten one level of React Fragments out of children. `React.Children.toArray`
+ * does NOT recursively unwrap fragments — this helper handles the common case
+ * of wrapping a single sub-component in `<>...</>`.
+ */
+function flattenChildren(children: ReactNode): ReactNode[] {
+  const flat: ReactNode[] = [];
+  Children.toArray(children).forEach((child) => {
+    if (isValidElement(child) && child.type === Fragment) {
+      flat.push(
+        ...Children.toArray((child as ReactElement<{ children: ReactNode }>).props.children),
+      );
+    } else {
+      flat.push(child);
+    }
+  });
+  return flat;
+}
+
+/**
+ * Compound layout primitive for semantic key/value pairs, rendered as `<dl>` / `<dt>` / `<dd>`.
+ * @see docs/components/DefinitionList.md
+ */
+const DefinitionListRoot = forwardRef<HTMLDListElement, DefinitionListProps>(
+  function DefinitionListRoot(
+    {
+      layout = 'horizontal',
+      termWidth,
+      spacing = 'sm',
+      dividers,
+      className,
+      style,
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    if (process.env.NODE_ENV !== 'production') {
+      flattenChildren(children).forEach((child) => {
+        if (child == null || typeof child === 'boolean') return;
+        if (!isValidElement(child) || child.type !== DefinitionListItem) {
+          console.warn(
+            '<DefinitionList> expects <DefinitionList.Item> children. Other children render but may break layout.',
+          );
+        }
+      });
+    }
+
+    const mergedStyle: CSSProperties | undefined = termWidth
+      ? ({ ['--dl-term-width' as string]: termWidth, ...style } as CSSProperties)
+      : style;
+
+    return (
+      <dl
+        ref={ref}
+        data-layout={layout}
+        data-spacing={spacing}
+        data-dividers={dividers ? 'true' : undefined}
+        className={clsx(styles.list, className)}
+        style={mergedStyle}
+        // {...rest} last so consumer overrides win (Pattern A).
+        {...rest}
+      >
+        {children}
+      </dl>
+    );
+  },
+);
+DefinitionListRoot.displayName = 'DefinitionList';
+
+/**
+ * Wrapper for one term + description pair (`DefinitionList.Item`).
+ * @see docs/components/DefinitionList.md
+ */
+// `display: contents` in horizontal layout so dt/dd join the parent dl's grid.
+export const DefinitionListItem = forwardRef<HTMLDivElement, DefinitionListItemProps>(
+  function DefinitionListItem({ className, children, ...rest }, ref) {
+    return (
+      <div ref={ref} className={clsx(styles.item, className)} {...rest}>
+        {children}
+      </div>
+    );
+  },
+);
+DefinitionListItem.displayName = 'DefinitionListItem';
+
+/**
+ * The label of one entry, rendered as `<dt>` (`DefinitionList.Term`).
+ * @see docs/components/DefinitionList.md
+ */
+export const DefinitionListTerm = forwardRef<HTMLElement, DefinitionListTermProps>(
+  function DefinitionListTerm({ className, children, ...rest }, ref) {
+    return (
+      <dt ref={ref} className={clsx(styles.term, className)} {...rest}>
+        {children}
+      </dt>
+    );
+  },
+);
+DefinitionListTerm.displayName = 'DefinitionListTerm';
+
+/**
+ * The value of one entry, rendered as `<dd>` with an optional leading `icon` (`DefinitionList.Description`).
+ * @see docs/components/DefinitionList.md
+ */
+export const DefinitionListDescription = forwardRef<HTMLElement, DefinitionListDescriptionProps>(
+  function DefinitionListDescription({ icon, className, children, ...rest }, ref) {
+    return (
+      <dd ref={ref} className={clsx(styles.description, className)} {...rest}>
+        {icon && (
+          <span className={styles.icon} aria-hidden="true">
+            {icon}
+          </span>
+        )}
+        {children}
+      </dd>
+    );
+  },
+);
+DefinitionListDescription.displayName = 'DefinitionListDescription';
+
+export const DefinitionList = Object.assign(DefinitionListRoot, {
+  Item: DefinitionListItem,
+  Term: DefinitionListTerm,
+  Description: DefinitionListDescription,
+});

package/src/components/DefinitionList/index.ts

@@ -0,0 +1,9 @@
+export {
+  DefinitionList,
+  type DefinitionListProps,
+  type DefinitionListLayout,
+  type DefinitionListSpacing,
+  type DefinitionListItemProps,
+  type DefinitionListTermProps,
+  type DefinitionListDescriptionProps,
+} from './DefinitionList';