@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Cluster/Cluster.module.scss

@@ -0,0 +1,145 @@
+@use './Cluster.tokens';
+
+.cluster {
+  display: flex;
+  flex-direction: row;
+}
+
+// Opt-in, via the `minWidth0` prop. As a flex or grid ITEM a Cluster keeps the
+// default `min-width: auto`, which floors it at its content's min-content size —
+// so a `<Text truncate>` inside never gets the chance to ellipsize and a clipping
+// ancestor hard-cuts it instead (issue #475).
+// This only means anything while `.cluster`'s overflow is non-scrollable: per CSS
+// Flexbox §4.5 a flex item keeps its automatic minimum size until its computed
+// overflow becomes scrollable. Giving `.cluster` `overflow: hidden`/`auto`/`scroll`
+// would therefore remove the floor by itself and make this prop dead code — but
+// `overflow: clip` would NOT, because clip is non-scrollable and still floors.
+// Measured; do not assume any overflow value will do.
+// Deliberately NOT on the base `.cluster` class: that would let every Cluster in the
+// codebase shrink below its content, changing layout for existing consumers. It
+// was tried and reverted. Measured on the playground Tenants mockup, whose inner
+// filter Cluster sits in a between-justified `wrap={false}` row inside a Card
+// (Card defaults to `overflow: hidden`): forcing `min-width: 0` shrinks that inner
+// Cluster by ~3px at 1920 rising to ~46px at 820, and the Card then clips up to
+// 34px off the trailing button. The buttons themselves never shrink — they
+// overflow the shrunken container and the Card cuts them.
+.minWidth0 {
+  min-width: 0;
+}
+
+// Opt-in, via `stretchWrapped` (#668). flex-grow distributes free space PER
+// FLEX LINE. On a line shared by several children, the `::before` spacer
+// (grow 999, basis 0) soaks up the slack, so the content-sized children
+// get a negligible share (grow 1 next to 999: at most 1px per 1000px of
+// slack); the spacer sits between the first child (`order: -1`, ahead of it)
+// and the rest, pushing them to the end. A non-first child alone on a wrapped
+// line has no spacer on that line, so its grow 1 takes the whole line.
+// Line breaking still counts the gap before the spacer, so a negative start
+// margin of one gap cancels it: the spacer adds no width, the switch happens
+// exactly when the content stops fitting, and a full-width first child keeps
+// the spacer on its own line instead of pushing it onto the second.
+// Child rules sit in `:where()` (zero specificity) so a child's own `flex`
+// or `max-width` class wins for that child.
+.stretchWrapped {
+  &::before {
+    content: '';
+    flex: 999 1 0;
+    /* stylelint-disable-next-line property-disallowed-list -- cancels the gap before the invisible spacer so it adds no width to line breaking; not layout on the component boundary. */
+    margin-inline-start: calc(-1 * var(--cluster-gap-current, 0px));
+  }
+}
+
+:where(.stretchWrapped > :first-child) {
+  order: -1;
+  max-width: 100%;
+}
+
+:where(.stretchWrapped > :not(:first-child)) {
+  flex: 1 1 auto;
+}
+
+// Opt-in, via `maxWidthFull` (#571): an inline (`as="span"`) cluster sizes to
+// its content, and with a nowrap truncating child that content is the full
+// title — so it overflows the line instead of ellipsizing at its edge.
+.maxWidthFull {
+  max-width: 100%;
+}
+
+// as="span": phrasing-content contexts (inside <button>, <a>, <label>) need
+// an inline-level box — a block flex container would break inline flow and
+// is invalid HTML there; this is the reason the span variant exists.
+.inline {
+  display: inline-flex;
+}
+
+.wrap {
+  flex-wrap: wrap;
+}
+
+.gapXs {
+  --cluster-gap-current: var(--cluster-gap-xs);
+
+  gap: var(--cluster-gap-current);
+}
+
+.gapSm {
+  --cluster-gap-current: var(--cluster-gap-sm);
+
+  gap: var(--cluster-gap-current);
+}
+
+.gapMd {
+  --cluster-gap-current: var(--cluster-gap-md);
+
+  gap: var(--cluster-gap-current);
+}
+
+.gapLg {
+  --cluster-gap-current: var(--cluster-gap-lg);
+
+  gap: var(--cluster-gap-current);
+}
+
+.gapXl {
+  --cluster-gap-current: var(--cluster-gap-xl);
+
+  gap: var(--cluster-gap-current);
+}
+
+.gap2xl {
+  --cluster-gap-current: var(--cluster-gap-2xl);
+
+  gap: var(--cluster-gap-current);
+}
+
+.justifyStart {
+  justify-content: flex-start;
+}
+
+.justifyCenter {
+  justify-content: center;
+}
+
+.justifyEnd {
+  justify-content: flex-end;
+}
+
+.justifyBetween {
+  justify-content: space-between;
+}
+
+.alignStart {
+  align-items: flex-start;
+}
+
+.alignCenter {
+  align-items: center;
+}
+
+.alignEnd {
+  align-items: flex-end;
+}
+
+.alignBaseline {
+  align-items: baseline;
+}

package/src/components/Cluster/Cluster.tokens.scss

@@ -0,0 +1,11 @@
+// Cluster.tokens.scss — Component-scoped tokens for <Cluster>. Each token
+// defaults to the primitive the SCSS used before this migration.
+:root {
+  // Gap per size
+  --cluster-gap-xs: var(--space-1);
+  --cluster-gap-sm: var(--space-2);
+  --cluster-gap-md: var(--space-3);
+  --cluster-gap-lg: var(--space-4);
+  --cluster-gap-xl: var(--space-6);
+  --cluster-gap-2xl: var(--space-8);
+}

package/src/components/Cluster/Cluster.tsx

@@ -0,0 +1,215 @@
+import { forwardRef, type HTMLAttributes, type Ref } from 'react';
+import clsx from 'clsx';
+import styles from './Cluster.module.scss';
+
+/** Horizontal gap between children. Values in pixels: 4 / 8 / 12 / 16 / 24 / 32. */
+export type ClusterGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+/** Main-axis distribution. `between` is the toolbar pattern. */
+export type ClusterJustify = 'start' | 'center' | 'end' | 'between';
+
+/** Cross-axis alignment. */
+export type ClusterAlign = 'start' | 'center' | 'end' | 'baseline';
+
+/**
+ * Rendered element. A small union rather than a fully generic polymorphic
+ * `as`, mirroring `TextAs`; details on the `as` prop.
+ */
+export type ClusterAs = 'div' | 'span' | 'section' | 'aside';
+
+export interface ClusterProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Element to render. Defaults to `'div'`.
+   * - `div` (default) — block-level flex container; right for nearly all uses.
+   * - `span` — renders `display: inline-flex`, for phrasing-content contexts
+   *   where a block element is invalid HTML: inside `<button>` (e.g. a
+   *   `ButtonGroup.Item` icon + label), `<a>`, or `<label>`.
+   * - `section` — only for a genuinely standalone, nameable region; pair with
+   *   `aria-label`/`aria-labelledby` (an unnamed section is just a div to AT).
+   * - `aside` — exposes a `complementary` landmark to screen readers; label it,
+   *   and never use it for mere visual grouping.
+   *
+   * `span` is the ONLY value valid inside `<button>`/`<a>`/`<label>` —
+   * `section` and `aside` are flow content and remain invalid HTML there.
+   */
+  as?: ClusterAs;
+  /**
+   * Gap between children, in pixels:
+   * `xs` (4) / `sm` (8) / `md` (12, default) / `lg` (16) / `xl` (24) / `2xl` (32).
+   */
+  gap?: ClusterGap;
+  /**
+   * Horizontal distribution.
+   * - `start` (default) — items at the start.
+   * - `center` — items centered.
+   * - `end` — items at the end. Canonical form-footer pattern.
+   * - `between` — first item at start, last at end, gap between. Canonical toolbar pattern (title left, actions right).
+   */
+  justify?: ClusterJustify;
+  /**
+   * Vertical alignment.
+   * - `start` / `center` (default) / `end` / `baseline`.
+   */
+  align?: ClusterAlign;
+  /**
+   * Lets the container shrink below its content's intrinsic width
+   * (`min-width: 0`), so a `<Text truncate>` inside can ellipsize instead of
+   * being hard-cut by a clipping ancestor.
+   *
+   * Reach for it when this Cluster is an item of a **row** flex container (or a
+   * grid item) that clips — a `Calendar` `renderEvent` chip, a `Card.Header`
+   * row. Without it the flex default (`min-width: auto`) floors the
+   * container at its content's min-content width and the ellipsis never
+   * appears. That floor applies because a Cluster sets no `overflow` — per CSS
+   * Flexbox §4.5 a flex item keeps its automatic minimum size while its computed
+   * `overflow` is non-scrollable (`visible` or `clip`); the scrollable values
+   * (`hidden`/`auto`/`scroll`) drop it to `0`. That is why a `<Text truncate>`
+   * (overflow hidden) never needs this and a Cluster around it does.
+   *
+   * It is a **no-op** inside a column `Stack` (the automatic minimum size
+   * applies only on the flex MAIN axis, so there is no horizontal floor), and
+   * inside a plain block or a table cell (the automatic minimum size applies
+   * to flex and grid ITEMS only, so `min-width: auto` is just `0` there). A table cell is
+   * a no-op for a different reason than it looks: auto table layout floors the
+   * cell at its content's min-content width regardless, so what makes text
+   * truncate there is `table-layout: fixed` or a `max-width` on the cell — not
+   * this prop.
+   *
+   * Opt-in rather than the default on purpose: a container that CAN shrink
+   * also VOLUNTEERS for shrink, so turning it on where the content is NOT
+   * truncatable (buttons, badges, icons) lets that content be clipped
+   * instead. Set it on the container whose text should give way, not on one
+   * holding controls.
+   *
+   * Related: `<Constrain flex="grow">` applies the same `min-width: 0` but
+   * also forces `flex: 1 1 0`, and renders a `<div>` — reach for this prop
+   * when you want only the shrink permission, or when you are inside a
+   * `<button>`/`<a>`/`<label>` where a `<div>` is invalid HTML.
+   *
+   * @default false
+   */
+  minWidth0?: boolean;
+  /**
+   * Caps the cluster at its container's width (`max-width: 100%`). Meant for
+   * `as="span"` inside running text: an inline cluster otherwise sizes to its
+   * content, so a `<Text as="span" truncate>` child with a long title makes
+   * the cluster overflow the paragraph instead of ellipsizing at the line
+   * edge. Combine with `wrap={false}` + a truncating child. The chip is one
+   * inline box: if the text before it leaves too little room on the line, the
+   * whole chip wraps to the next line, then ellipsizes at the full paragraph
+   * width. Phrasing-safe (still a span) — unlike `<Constrain maxWidth>`, which
+   * renders a `<div>` that is invalid inside `<p>` (#571).
+   *
+   * For an entity link row (icon, KEY, title, status, adornments) prefer
+   * `<EntityChip truncate trailing={…}>`, which does exactly this.
+   *
+   * @default false
+   */
+  maxWidthFull?: boolean;
+  /**
+   * Content-driven switch between one row and stacked. While the children fit
+   * on one line they stay content-sized and the free space collects between
+   * the first child and the rest (the rest sit at the end). When they no
+   * longer fit, every child that wraps onto its own line stretches to fill
+   * that line.
+   *
+   * Canonical case: a status pill plus a `<Grid columns={2}>` of two buttons —
+   * pill left and buttons right while there is room, buttons dropping under the
+   * pill at full width (equal columns) when there is not. No breakpoint to guess,
+   * unlike `Grid collapseBelow`.
+   *
+   * How: an invisible `::before` spacer soaks up a shared line's slack, so the
+   * children there get a negligible share (at most 1px per 1000px of slack); a
+   * non-first child alone on a wrapped line takes the whole line. Children
+   * wrapped together share it. The spacer cancels its own gap, so it adds no
+   * width: the switch happens exactly when the content stops fitting, also
+   * with a single child or `as="span"`.
+   *
+   * Limits: `justify` is inert while this is on (the spacer owns the slack);
+   * `wrap={false}` makes it moot (nothing wraps); a consumer `order` on
+   * children breaks it — don't. A child's own `flex` (via its `className`)
+   * overrides the stretch for that child. "First child" means the first
+   * ELEMENT: a leading bare text node is not it — wrap text in an element
+   * (e.g. `<Text>`).
+   *
+   * @default false
+   */
+  stretchWrapped?: boolean;
+  /**
+   * Whether children wrap to additional lines when the container is narrow.
+   * - `true` (default) — natural for toolbars and tag lists.
+   * - `false` — use sparingly, when overflow is preferable to wrapping
+   *   (e.g. inside a narrow table cell with fixed-width action buttons).
+   */
+  wrap?: boolean;
+}
+
+const gapClass: Record<ClusterGap, string> = {
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
+  '2xl': styles.gap2xl,
+};
+
+const justifyClass: Record<ClusterJustify, string> = {
+  start: styles.justifyStart,
+  center: styles.justifyCenter,
+  end: styles.justifyEnd,
+  between: styles.justifyBetween,
+};
+
+const alignClass: Record<ClusterAlign, string> = {
+  start: styles.alignStart,
+  center: styles.alignCenter,
+  end: styles.alignEnd,
+  baseline: styles.alignBaseline,
+};
+
+/**
+ * Horizontal layout primitive that wraps.
+ * @see docs/components/Cluster.md
+ */
+export const Cluster = forwardRef<HTMLElement, ClusterProps>(function Cluster(
+  {
+    as = 'div',
+    gap = 'md',
+    justify = 'start',
+    align = 'center',
+    wrap = true,
+    minWidth0 = false,
+    stretchWrapped = false,
+    maxWidthFull = false,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const Component = as;
+  // The rendered element type varies across the union, so the JSX ref slot
+  // expects an intersection of the element ref types. Cast like Text does —
+  // the runtime type is always correct because Component is exactly `as`.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const domRef = ref as unknown as Ref<any>;
+  // className merged via clsx so consumer classes stack with ours;
+  // {...props} last so the consumer can override anything (Pattern A).
+  return (
+    <Component
+      ref={domRef}
+      className={clsx(
+        styles.cluster,
+        as === 'span' && styles.inline,
+        gapClass[gap],
+        justifyClass[justify],
+        alignClass[align],
+        wrap && styles.wrap,
+        minWidth0 && styles.minWidth0,
+        stretchWrapped && styles.stretchWrapped,
+        maxWidthFull && styles.maxWidthFull,
+        className,
+      )}
+      {...props}
+    />
+  );
+});

package/src/components/Cluster/index.ts

@@ -0,0 +1,2 @@
+export { Cluster } from './Cluster';
+export type { ClusterProps, ClusterAs, ClusterGap, ClusterJustify, ClusterAlign } from './Cluster';

package/src/components/Code/Code.module.scss

@@ -0,0 +1,28 @@
+@use './Code.tokens';
+
+.code {
+  font-family: var(--font-family-mono);
+  font-size: var(--code-font-size);
+
+  // stylelint-disable-next-line property-disallowed-list -- inline chip padding (component-internal, not at the boundary)
+  padding: 0 var(--code-padding-x);
+  border-radius: var(--code-radius);
+  background: var(--code-bg);
+  color: var(--code-fg);
+}
+
+.toneDefault {
+  color: var(--code-fg-default);
+}
+
+.toneMuted {
+  color: var(--code-fg-muted);
+}
+
+.toneAccent {
+  color: var(--code-fg-accent);
+}
+
+.toneDanger {
+  color: var(--code-fg-danger);
+}

package/src/components/Code/Code.tokens.scss

@@ -0,0 +1,15 @@
+// Code.tokens.scss — Component-scoped tokens for <Code>. Covers the inline mono chip's surface + per-tone foreground. --font-family-mono stays primitive per the don't-tokenize list.
+:root {
+  // Surface + base typography
+  --code-font-size: var(--font-size-code);
+  --code-padding-x: var(--space-1);
+  --code-radius: var(--radius-sm);
+  --code-bg: var(--color-bg-muted);
+  --code-fg: var(--color-fg);
+
+  // Tone — foreground only (background stays muted across tones)
+  --code-fg-default: var(--color-fg);
+  --code-fg-muted: var(--color-fg-muted);
+  --code-fg-accent: var(--color-accent);
+  --code-fg-danger: var(--color-danger);
+}

package/src/components/Code/Code.tsx

@@ -0,0 +1,44 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './Code.module.scss';
+
+/** Color tone. */
+export type CodeTone = 'default' | 'muted' | 'accent' | 'danger';
+
+export interface CodeProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Color tone for the code text. The chip background stays the same;
+   * only the text color changes.
+   * - `default` — `--color-fg`
+   * - `muted` — `--color-fg-muted`
+   * - `accent` — `--color-accent`
+   * - `danger` — `--color-danger`
+   */
+  tone?: CodeTone;
+  /** Code content. */
+  children: ReactNode;
+}
+
+const TONE_CLASS: Record<CodeTone, string> = {
+  default: styles.toneDefault,
+  muted: styles.toneMuted,
+  accent: styles.toneAccent,
+  danger: styles.toneDanger,
+};
+
+/**
+ * Inline `<code>` primitive: monospace text with a subtle chip background.
+ * @see docs/components/Code.md
+ */
+export const Code = forwardRef<HTMLElement, CodeProps>(function Code(
+  { tone = 'default', className, children, ...rest },
+  ref,
+) {
+  // className merged above via clsx so consumer extensions stack with our classes;
+  // {...rest} last so any other consumer-passed attr can override ours (Pattern A).
+  return (
+    <code ref={ref} className={clsx(styles.code, TONE_CLASS[tone], className)} {...rest}>
+      {children}
+    </code>
+  );
+});

package/src/components/Code/index.ts

@@ -0,0 +1,2 @@
+export { Code } from './Code';
+export type { CodeProps, CodeTone } from './Code';

package/src/components/CodeBlock/CodeBlock.module.scss

@@ -0,0 +1,146 @@
+@use './CodeBlock.tokens';
+@use '../../styles/mixins' as *;
+
+.root {
+  border: var(--border-width) solid var(--code-block-border-color);
+  border-radius: var(--code-block-radius);
+  background: var(--code-block-bg);
+  color: var(--code-block-fg);
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-2);
+  min-height: var(--size-md);
+  padding-inline: var(--code-block-padding-x) var(--space-2);
+  border-bottom: var(--border-width) solid var(--code-block-border-color);
+  border-start-start-radius: inherit;
+  border-start-end-radius: inherit;
+  background: var(--code-block-header-bg);
+
+  // The header's own border is the divider; the tab strip's baseline would double it.
+  --tabs-border-color: transparent;
+}
+
+// Tabs' own scroll wrapper already has min-width: 0, so a long strip scrolls
+// inside the header; the title needs the same to truncate instead of pushing.
+.title {
+  @include truncate;
+
+  min-width: 0;
+  font-size: var(--font-size-sm);
+  color: var(--color-fg-muted);
+}
+
+.actions {
+  display: flex;
+  flex-shrink: 0;
+  gap: var(--space-1);
+}
+
+.body {
+  overflow-x: auto;
+  padding-block: var(--code-block-padding-y);
+  font-family: var(--font-family-mono);
+  font-size: var(--code-block-font-size);
+  line-height: var(--code-block-line-height);
+  white-space: pre;
+  tab-size: 2;
+
+  &:focus-visible {
+    @include focus-ring($offset: calc(var(--ring-width) * -1));
+  }
+}
+
+.wrap {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+// The body's own internal scroll box (like ScrollArea), not outer layout.
+.maxXs {
+  max-height: var(--measure-xs);
+  overflow-y: auto;
+}
+
+.maxSm {
+  max-height: var(--measure-sm);
+  overflow-y: auto;
+}
+
+.maxMd {
+  max-height: var(--measure-md);
+  overflow-y: auto;
+}
+
+.maxLg {
+  max-height: var(--measure-lg);
+  overflow-y: auto;
+}
+
+.maxXl {
+  max-height: var(--measure-xl);
+  overflow-y: auto;
+}
+
+// inline-block shrink-wraps to the longest line but never less than the body,
+// so a highlighted line's tint spans the full scroll width, not just the viewport.
+.lines {
+  display: inline-block;
+  min-width: 100%;
+  font: inherit;
+}
+
+// Inline-block, not block: block-level lines make innerText add a break on top
+// of the '\n' between them. min-height gives an empty line its line box.
+.line {
+  display: inline-block;
+  min-width: 100%;
+  min-height: 1lh;
+  vertical-align: top;
+  padding-inline: var(--code-block-padding-x);
+
+  // Every line reserves the bar so highlighting never shifts text; a logical
+  // border (not an inset box-shadow) keeps the bar on the start side in RTL.
+  border-inline-start: var(--border-width-strong) solid transparent;
+
+  &[data-highlighted] {
+    border-inline-start-color: var(--code-block-line-highlight-bar);
+    background: var(--code-block-line-highlight-bg);
+  }
+}
+
+.keyword {
+  color: var(--code-block-syntax-keyword);
+}
+
+.string {
+  color: var(--code-block-syntax-string);
+}
+
+.number {
+  color: var(--code-block-syntax-number);
+}
+
+.comment {
+  color: var(--code-block-syntax-comment);
+  font-style: italic;
+}
+
+.function {
+  color: var(--code-block-syntax-function);
+}
+
+.property {
+  color: var(--code-block-syntax-property);
+}
+
+.punctuation {
+  color: var(--code-block-syntax-punctuation);
+}
+
+.plain {
+  color: var(--code-block-syntax-plain);
+}

package/src/components/CodeBlock/CodeBlock.tokens.scss

@@ -0,0 +1,27 @@
+// CodeBlock.tokens.scss — Component-scoped tokens for <CodeBlock>. Surface, highlighted line and the eight syntax colours. `--code-*` belongs to the inline <Code> chip.
+:root {
+  // Surface
+  --code-block-bg: var(--color-bg-subtle);
+  --code-block-border-color: var(--color-border);
+  --code-block-radius: var(--radius-md);
+  --code-block-header-bg: var(--color-bg);
+  --code-block-fg: var(--color-fg);
+  --code-block-font-size: var(--font-size-code);
+  --code-block-line-height: var(--line-height-normal);
+  --code-block-padding-y: var(--space-3);
+  --code-block-padding-x: var(--space-4);
+
+  // Highlighted line
+  --code-block-line-highlight-bg: var(--color-accent-bg-subtle);
+  --code-block-line-highlight-bar: var(--color-accent);
+
+  // Syntax — every colour is gated at AA on the surface and the highlighted line
+  --code-block-syntax-keyword: var(--color-palette-violet-fg);
+  --code-block-syntax-string: var(--color-palette-green-fg);
+  --code-block-syntax-number: var(--color-warning-strong);
+  --code-block-syntax-comment: var(--color-fg-muted);
+  --code-block-syntax-function: var(--color-palette-blue-fg);
+  --code-block-syntax-property: var(--color-palette-teal-fg);
+  --code-block-syntax-punctuation: var(--color-fg-muted);
+  --code-block-syntax-plain: var(--code-block-fg);
+}