@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/IconTile/IconTile.tokens.scss

@@ -0,0 +1,16 @@
+// IconTile.tokens.scss — Component tokens for <IconTile>. Box size per `size`
+// and corner radius per `shape`; default to primitives. The bg/fg tint is set
+// at runtime via the --icon-tile-bg / --icon-tile-fg custom properties (from a
+// PaletteColor), so it is not declared here.
+:root {
+  --icon-tile-size-xs: var(--size-xs); // 20px
+  --icon-tile-size-sm: var(--size-sm); // 24px
+  --icon-tile-size-md: var(--size-md); // 32px
+  --icon-tile-size-lg: var(--size-lg); // 40px
+  // `inline` is font-relative (#577): the tile is the surrounding text's
+  // font-size, the glyph a bit smaller.
+  --icon-tile-size-inline: 1em;
+  --icon-tile-glyph-inline: 0.75em;
+  --icon-tile-radius-square: var(--radius-md);
+  --icon-tile-radius-circle: var(--radius-full);
+}

package/src/components/IconTile/IconTile.tsx

@@ -0,0 +1,91 @@
+import { forwardRef, type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import { paletteTokens, type PaletteColor } from '../../palette';
+import styles from './IconTile.module.scss';
+
+type StyleWithVars = CSSProperties & { [key: `--${string}`]: string | number };
+
+/**
+ * Tile box size — `xs` 20 / `sm` 24 / `md` 32 / `lg` 40 px (sizes the tile, not
+ * the icon), or `inline`: `1em`, following the surrounding text (sizes the icon
+ * too).
+ */
+export type IconTileSize = 'inline' | 'xs' | 'sm' | 'md' | 'lg';
+
+/** Tile shape — `'square'` (radius-md, default) or `'circle'` (radius-full). */
+export type IconTileShape = 'square' | 'circle';
+
+export interface IconTileProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
+  /**
+   * The icon to frame — a lucide icon (sized by you, ~14–20px), custom SVG, or
+   * any ReactNode. Required; IconTile is purely an icon frame.
+   */
+  icon: ReactNode;
+  /**
+   * Palette color for the tint — one of the 30 categorical colors. Defaults to
+   * `'slate'`. Categorical (visual identity), NOT semantic; for status use a
+   * `<Badge tone>` instead.
+   */
+  color?: PaletteColor;
+  /**
+   * Tile box size. `'xs'` 20 / `'sm'` 24 / `'md'` 32 (**default**) / `'lg'` 40 px.
+   * Sizes the tile box — size your icon child separately. `'xs'` brackets a
+   * 14px glyph with ~3px of padding so the tile sits inside a text / Badge /
+   * EntityChip row without growing it.
+   *
+   * `'inline'` is font-relative: a `1em` tile (the surrounding text's
+   * font-size) centred on the text's capitals, whose glyph the tile sizes to
+   * `0.75em` — a direct `<svg>` child's (a lucide icon's) own `size` is
+   * overridden; wrap nothing around the icon. Use it in text contexts
+   * (`EntityChip` `icon` / `trailing`, `Badge` rows, dense lists, running
+   * text) where even `xs` towers over the capitals. It follows `font-size`,
+   * so there is no size decision per call site. Not for standalone tiles — it is only as big as the text.
+   */
+  size?: IconTileSize;
+  /** `'square'` (radius-md, **default**) or `'circle'` (radius-full). */
+  shape?: IconTileShape;
+  /**
+   * Accessible name. Omit (**default**) → the tile is decorative
+   * (`aria-hidden`), for use beside text that carries the meaning. Set it →
+   * `role="img"` + `aria-label`, for a standalone tile whose icon is the only
+   * indicator.
+   */
+  label?: string;
+}
+
+/**
+ * A small decorative tile that frames a single icon, tinted by a Palette color.
+ * @see docs/components/IconTile.md
+ */
+export const IconTile = forwardRef<HTMLSpanElement, IconTileProps>(function IconTile(
+  { icon, color = 'slate', size = 'md', shape = 'square', label, className, style, ...rest },
+  ref,
+) {
+  const { bg, fg } = paletteTokens(color);
+  // Pass the palette tokens through as CSS custom properties; the stylesheet
+  // reads them (background/color live in .module.scss). DRY — no hand-kept
+  // 30-color class list — and token-correct (values are var(--color-palette-…),
+  // never raw). Same dynamic-inline-var pattern as <Avatar>/<Progress>.
+  const cssVars: StyleWithVars = { '--icon-tile-bg': bg, '--icon-tile-fg': fg };
+
+  // Decorative by default; a non-empty `label` promotes it to a labelled image.
+  // Empty/whitespace label stays decorative — aria-label="" would be announced
+  // with no name. Spread before {...rest} (Pattern A) so a consumer can override
+  // role/aria-*.
+  const a11y =
+    label != null && label.trim() !== ''
+      ? { role: 'img', 'aria-label': label }
+      : { 'aria-hidden': true as const };
+
+  return (
+    <span
+      ref={ref}
+      className={clsx(styles.tile, styles[`size-${size}`], styles[`shape-${shape}`], className)}
+      style={{ ...cssVars, ...style }}
+      {...a11y}
+      {...rest}
+    >
+      {icon}
+    </span>
+  );
+});

package/src/components/IconTile/index.ts

@@ -0,0 +1,2 @@
+export { IconTile } from './IconTile';
+export type { IconTileProps, IconTileSize, IconTileShape } from './IconTile';

package/src/components/Image/Image.module.scss

@@ -0,0 +1,266 @@
+@use './Image.tokens';
+@use '../../styles/mixins' as *;
+@use '../Button/Button.tokens';
+
+.wrapper {
+  display: block;
+  position: relative; // internal anchor for the absolute overlays (Rule 4 OK)
+  width: 100%; // fills the container; parent owns outer width (Rule 4: 100% OK)
+  overflow: hidden; // clip the image to the rounded corners
+  background: var(--image-bg);
+}
+
+// Transparent assets show their surface once loaded; skeleton/error keep the fill.
+.wrapper[data-background='none'][data-state='loaded'] {
+  background: transparent;
+}
+
+// Fixed-square `size` variant — opt-in, overrides the default width:100% (the
+// compound `.wrapper.sizeX` selector beats `.wrapper` so order is irrelevant).
+// A component-owned fixed size, mirroring Avatar's size scale; `flex-shrink: 0`
+// keeps the box from squishing in a flex row / table cell.
+// Each size also picks the error icon it can hold — see `.errorIcon`.
+.wrapper.sizeXs {
+  --image-error-icon-size: var(--image-error-icon-xs);
+
+  width: var(--image-size-xs);
+  height: var(--image-size-xs);
+  flex-shrink: 0;
+}
+
+.wrapper.sizeSm {
+  --image-error-icon-size: var(--image-error-icon-sm);
+
+  width: var(--image-size-sm);
+  height: var(--image-size-sm);
+  flex-shrink: 0;
+}
+
+.wrapper.sizeMd {
+  --image-error-icon-size: var(--image-error-icon-md);
+
+  width: var(--image-size-md);
+  height: var(--image-size-md);
+  flex-shrink: 0;
+}
+
+.wrapper.sizeLg {
+  --image-error-icon-size: var(--image-error-icon-lg);
+
+  width: var(--image-size-lg);
+  height: var(--image-size-lg);
+  flex-shrink: 0;
+}
+
+.radiusNone {
+  border-radius: var(--image-radius-none);
+}
+
+.radiusSm {
+  border-radius: var(--image-radius-sm);
+}
+
+.radiusMd {
+  border-radius: var(--image-radius-md);
+}
+
+.radiusLg {
+  border-radius: var(--image-radius-lg);
+}
+
+.radiusFull {
+  border-radius: var(--image-radius-full);
+}
+
+.img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: var(--image-object-fit, cover); // intrinsic (Rule 4 OK; Avatar precedent)
+  object-position: var(--image-object-position, center);
+  opacity: var(--opacity-hidden);
+  transition: opacity var(--image-transition);
+}
+
+.wrapper[data-state='loaded'] .img {
+  opacity: var(--opacity-visible);
+}
+
+.wrapper[data-state='error'] .img {
+  display: none;
+}
+
+.overlay {
+  position: absolute;
+  inset: 0;
+}
+
+// Smallest box the full fluid tile (icon + message + Retry) fits in — see the
+// `@container` rule below. Measured in Chromium at default tokens: icon 28 +
+// gap 8 + at most two lines of text 34 (clamped, see `.errorText`) + gap 8 +
+// `sm` Button 24 ≈ 103px tall at most (the line-height is 17.14px, not 17),
+// whatever the message — do not lower the height threshold below 104. The width is
+// set by the widest shipped Retry label (ru "Повторить", 85px; en 55px). SCSS
+// constants because container-query conditions can't read custom properties
+// (same as `_internal/collapse.scss`).
+// ponytail: fixed thresholds. They hold at default tokens for the shipped
+// Retry labels. A longer Retry label (a new locale or a consumer i18n
+// override), or larger `--image-error-gap` / `--image-error-font-size` / `sm`
+// Button tokens, needs these raised to match.
+$error-full-min-width: 96px;
+$error-full-min-height: 104px;
+
+.error {
+  position: absolute;
+  inset: 0;
+
+  // A size container: the tile is `inset: 0`, so its box comes from the
+  // wrapper and never from its contents, which is what makes size containment
+  // safe here and lets its children ask how much room they got (#542).
+  container-type: size;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--image-error-gap);
+  background: var(--image-error-bg);
+  color: var(--image-error-fg);
+}
+
+.errorText {
+  // At most two lines: a message wrapping freely made the tile's height (and
+  // so the threshold below) depend on the locale and on consumer i18n
+  // overrides (#542 review). Two, not one, so the ru message is shown in full
+  // from 128px wide instead of truncated up to ~197px. The full text stays in
+  // the DOM for screen readers either way.
+  // stylelint-disable-next-line property-no-vendor-prefix, value-no-vendor-prefix -- line clamping has no unprefixed form with cross-browser support
+  display: -webkit-box;
+  max-width: 100%;
+  overflow: hidden;
+  font-size: var(--image-error-font-size);
+  text-align: center;
+  // stylelint-disable-next-line property-no-vendor-prefix -- see display above
+  -webkit-box-orient: vertical;
+  // stylelint-disable-next-line property-no-vendor-prefix -- see display above
+  -webkit-line-clamp: 2;
+}
+
+// #542: in a box too narrow or short for the full tile, Retry landed past the
+// wrapper's `overflow: hidden` clip — painted nowhere, still in the tab order —
+// the #538 defect on the fluid branch. Degrade the same way the sized tile
+// does: icon only. Retry is `display: none`, so it leaves the tab order; the
+// message is visually hidden, not removed, because in this branch it is the
+// only thing naming the failure (the icon carries `alt` alone).
+// `.error .retry` / `.error .errorText` (0,2,0) beat Button's own `.button`
+// (0,1,0) on specificity, not on stylesheet order.
+@container (width < #{$error-full-min-width}) or (height < #{$error-full-min-height}) {
+  .error .errorText {
+    @include visually-hidden;
+  }
+
+  .error .retry {
+    display: none;
+  }
+
+  // The fluid icon is a fixed 28px; a box smaller than that clips it. Let it
+  // shrink with the tile, as the sized branch's `.errorIcon` does.
+  .error svg {
+    max-width: 100%;
+    max-height: 100%;
+  }
+}
+
+// An unreserved wrapper (no `size`, no `aspectRatio`) has no in-flow content
+// once the image fails, so it collapsed to height 0 (#542). Give it an in-flow
+// spacer, error state only, so a loaded image is untouched; the rule above
+// then makes it an icon-only tile. A spacer, NOT `min-height`: `min-height`
+// beats a consumer's own `height`, so a 24px thumbnail sized by `className`
+// would grow to 40px on error. The spacer only sets the height when it is
+// `auto`. An explicit `height` or CSS `aspect-ratio` still wins, and the
+// wrapper's `overflow: hidden` clips the leftover spacer.
+.unreserved[data-state='error']::before {
+  content: '';
+  display: block;
+  height: var(--image-error-min-height);
+}
+
+// The sized error tile is this icon and nothing else (#538), so it is sized to
+// the box it sits in rather than to lucide's attribute: a component-owned
+// intrinsic size like `.wrapper.sizeX` above, not layout (Rule 4 OK). Only the
+// sized branch renders it, so the custom property is always set by one of those
+// four rules — the `100%` is what happens if that ever stops being true. Without
+// it the declaration would be invalid at computed-value time and the icon would
+// fall back to lucide's own 24px attribute, overflowing xs and sm again.
+.errorIcon {
+  width: var(--image-error-icon-size, 100%);
+  height: var(--image-error-icon-size, 100%);
+}
+
+// A custom `fallback` REPLACES the built-in tile, so it gets the same slot that
+// tile has. A bare child is in flow, and when the image is also interactive it
+// flows after `.trigger` (height: 100%) and lands entirely outside the
+// wrapper's clip — the #538 defect, reached through the escape hatch documented
+// for it. This bounds the fallback to the box; what the consumer puts inside
+// the box is still theirs to fit. Applied only where the wrapper's height is
+// its own (`size` or `aspectRatio`) — see the comment at the call site.
+.fallback {
+  position: absolute;
+  inset: 0;
+}
+
+// Interactive trigger — a chromeless <button> wrapping the image (interactive /
+// onClick). No padding/border/background; fills the wrapper box; hugs its corners.
+.trigger {
+  display: block;
+  width: 100%;
+  height: 100%;
+  padding: 0;
+  border: 0;
+  background: none;
+  cursor: pointer;
+  border-radius: inherit;
+  color: inherit;
+}
+
+.trigger:disabled {
+  cursor: default;
+}
+
+// The wrapper has overflow:hidden, which would clip a ring drawn on the inner
+// button — so render the focus ring on the wrapper (its own overflow does not clip
+// its own outline). Follows the wrapper's border-radius.
+.wrapper:has(.trigger:focus-visible) {
+  @include focus-ring(var(--image-ring));
+}
+
+// The error column fills the wrapper (`.error` is `inset: 0`) and centres its
+// children, so in a small square box the Retry button's bottom edge could land
+// EXACTLY on the wrapper's bottom — measured at 0.00px of clearance in the
+// 80x80 `radius` examples, where the flex items shrank to fit and the column
+// ended up exactly as tall as the box. Since #542 a box that short gets the
+// icon-only tile (no Retry at all); the inset ring still covers a Retry that
+// sits within a few px of the edge just above the threshold. `.wrapper` is
+// `overflow: hidden`, so an
+// outset ring's entire bottom band (2px offset + 2px width) falls outside the
+// clip and is never painted: a keyboard user tabbing to Retry gets a ring with
+// its bottom edge missing. Pre-existing; #523's geometry sweep is what made it
+// visible, and #524 is its first catch.
+
+// Drawn inset instead — a wrapper's overflow cannot clip a ring that is inside
+// the element's own border box, at any wrapper size.
+
+// What the inset band covers (mixins.scss requires recording this at an inset
+// call site): the outermost 2px of the button — its 1px
+// `--color-border-strong` border and 1px of its `--color-bg` fill. The label
+// sits inside the button's padding and is untouched, and the border is still
+// the marker in the three unfocused states. Cheap trade for a ring that exists.
+
+// Scoped to Image's error state rather than to `Button`, which is a shared
+// primitive whose outset ring is correct everywhere else. `.error .retry` is
+// 0,3,0 against `Button`'s own `.button:focus-visible` at 0,2,0, so it wins on
+// specificity and not on stylesheet order. It passes `var(--button-ring)`
+// explicitly so the colour keeps following a consumer's Button ring override —
+// only the offset changes here.
+.error .retry:focus-visible {
+  @include focus-ring(var(--button-ring), calc(-1 * var(--ring-offset)));
+}

package/src/components/Image/Image.tokens.scss

@@ -0,0 +1,55 @@
+:root {
+  // Overridable so a consumer painting Image on a non-page surface can supply a
+  // ring that actually contrasts with it. Lightbox does exactly that: its
+  // thumbnails sit on a scrim that is dark in BOTH themes, where the light
+  // --ring-accent falls under 1.4.11's 3:1 (#505). No ratio quoted: the surface
+  // is a composite of --color-bg-overlay-strong, not a token, so no @contrast
+  // annotation could recompute it — contrast.test.ts composites and asserts it.
+  --image-ring: var(--ring-accent);
+
+  --image-radius-none: 0;
+  --image-radius-sm: var(--radius-sm);
+  --image-radius-md: var(--radius-md);
+  --image-radius-lg: var(--radius-lg);
+  --image-radius-full: var(--radius-full);
+
+  // Fixed-square sizes (the `size` prop). Aligned to the shared --size-* scale
+  // so a sized Image lines up with an Avatar / Button of the same size key.
+  --image-size-xs: var(--size-xs);
+  --image-size-sm: var(--size-sm);
+  --image-size-md: var(--size-md);
+  --image-size-lg: var(--size-lg);
+
+  --image-bg: var(--color-bg-muted);
+  --image-transition: var(--transition-base);
+
+  --image-error-bg: var(--color-bg-muted);
+  --image-error-fg: var(--color-fg-muted);
+  --image-error-gap: var(--space-2);
+  --image-error-font-size: var(--font-size-sm);
+
+  // Spacer height for a FAILED image with no box of its own (no `size`, no
+  // `aspectRatio`), which otherwise collapses to 0 (#542). One `lg` control
+  // high: room for the 28px error icon, not for the full tile.
+  --image-error-min-height: var(--size-lg);
+
+  // Error icon in the fixed-`size` branch, where the icon IS the tile (#538):
+  // no text, no Retry, so it has to fit INSIDE a 20/24/32/40px box rather than
+  // overflow it the way the fluid tile's 28px icon did at xs and sm. ~60% of
+  // the box, rounded to an even pixel, leaving 4/5/6/8px of clearance per side.
+  // Per-size literals rather than a percentage so the icon lands on whole
+  // pixels at every size (the Switch thumb/track scale does the same).
+  // COUPLED, deliberately and not derived: these are literals while the boxes
+  // above are `var(--size-*)`, which is shared and runtime-overridable, so a
+  // theme that moves the shared scale unpicks the ~60% relationship — an icon
+  // too small on a bigger box, or overflowing a smaller one. Deriving them
+  // (`calc(var(--size-sm) * 0.6)`) would track the scale but give 14.4 / 19.2px
+  // at sm and md, losing exactly the whole-pixel property that is the reason
+  // for the literals. The trade is whole pixels on the default scale over
+  // automatic tracking of a scale nothing in this repo overrides; a theme that
+  // does override it overrides these four too.
+  --image-error-icon-xs: 12px;
+  --image-error-icon-sm: 14px;
+  --image-error-icon-md: 20px;
+  --image-error-icon-lg: 24px;
+}