@50arms/ui 0.0.0-stage → 35.2.0

package/dist/lib/component-guidance.js

@@ -0,0 +1,297 @@
+const s = String.raw`"[^"\n]*"|'[^'\n]*'|\`[^\`]*\``;
+function o(t) {
+  const e = t > 1 ? `|${o(t - 1)}` : "";
+  return String.raw`\{(?:[^{}"'\`]|${s}${e})*\}`;
+}
+const a = String.raw`(?:[^>{}"'/]|"[^"]*"|'[^']*'|${o(3)})`;
+function i(t, e) {
+  return String.raw`\s${t}\s*=\s*(?:"${e}"|'${e}'|\{\s*(?:"${e}"|'${e}')\s*\})`;
+}
+function r(t, e, n) {
+  return String.raw`<${t}\b${a}*?${i(e, n)}`;
+}
+const d = [
+  // ---- native HTML / raw ARIA — always wrong; the library owns these shapes.
+  {
+    id: "raw-button",
+    pattern: /<button\b/,
+    preferInstead: ["Button"],
+    reason: "a native <button> — the library's Button carries focus, hover and disabled states the raw element does not."
+  },
+  {
+    id: "raw-video",
+    pattern: /<video\b/,
+    preferInstead: ["VideoPlayer"],
+    reason: "a native <video> — VideoPlayer carries the accessible name, preload=metadata, caption tracks and the can't-play fallback a raw element lacks (and FileCover is the fixed-size cover for a file that may be a video). DX-3982."
+  },
+  {
+    id: "raw-input",
+    pattern: /<input\b/,
+    preferInstead: ["Input"],
+    reason: "a native <input> — use the library's Input."
+  },
+  {
+    id: "raw-select",
+    pattern: /<select\b/,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["Select", "Combobox"],
+    reason: "a native <select> — use the library's Select (or Combobox for a searchable list)."
+  },
+  {
+    id: "raw-textarea",
+    pattern: /<textarea\b/,
+    preferInstead: ["Textarea"],
+    reason: "a native <textarea> — use the library's Textarea (or see textarea-for-prose if this holds human-written text)."
+  },
+  {
+    id: "raw-dialog",
+    pattern: /<dialog\b/,
+    preferInstead: ["Dialog"],
+    reason: "a native <dialog> — use the library's Dialog."
+  },
+  {
+    id: "raw-pre",
+    pattern: /<pre\b/,
+    preferInstead: ["Markdown"],
+    reason: "<pre> renders literal text; prose or a human-written document is markdown and should render through Markdown. Real code or log output is the one case <pre> still fits."
+  },
+  {
+    id: "raw-clipboard-write",
+    pattern: /navigator\.clipboard\.writeText\s*\(/,
+    preferInstead: ["CopyValue", "copyText"],
+    reason: "a raw navigator.clipboard.writeText is refused in some in-app browsers and has no outcome shown — CopyValue is a value with its one-click copy and an announced result; copyText is the same copy with the execCommand fallback when you need the act without the control."
+  },
+  {
+    id: "role-menu",
+    pattern: /role\s*=\s*["']menu["']/,
+    preferInstead: ["Menu"],
+    reason: 'a hand-rolled role="menu" — use Menu, which owns focus and keyboard navigation for you.'
+  },
+  {
+    id: "role-listbox",
+    pattern: /role\s*=\s*["']listbox["']/,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["Combobox", "Select"],
+    reason: 'a hand-rolled role="listbox" — use Combobox (searchable) or Select.'
+  },
+  {
+    id: "role-dialog",
+    pattern: /role\s*=\s*["']dialog["']/,
+    preferInstead: ["Dialog"],
+    reason: 'a hand-rolled role="dialog" — use Dialog, which owns focus trapping and dismissal for you.'
+  },
+  {
+    id: "role-tab",
+    pattern: /role\s*=\s*["']tab["']/,
+    preferInstead: ["Tabs"],
+    reason: 'a hand-rolled role="tab" — use Tabs.'
+  },
+  // ---- basic @50arms/ui primitive superseded by a richer one for its case.
+  {
+    id: "textarea-for-prose",
+    pattern: /<Textarea\b/,
+    preferInstead: ["InlineMarkdownEdit", "MarkdownEditor"],
+    reason: "Textarea holds plain text; multi-line human-written prose is markdown and belongs in InlineMarkdownEdit (read in place, edited in place) or MarkdownEditor."
+  },
+  {
+    id: "inline-edit-multiline",
+    pattern: new RegExp(r("InlineEdit", "lineMode", "multiline")),
+    preferInstead: ["InlineMarkdownEdit"],
+    reason: "a multiline InlineEdit holds prose; InlineMarkdownEdit renders and edits it as markdown in the same place."
+  },
+  {
+    id: "ghost-text-button",
+    // The attribute, the rest of the SAME opening tag, its closing `>` (a `/>`
+    // self-closing tag cannot match), then a first child that is text.
+    pattern: new RegExp(`${r("Button", "variant", "ghost")}${a}*>\\s*[^\\s<{]`),
+    preferInstead: ["IconButton"],
+    reason: "a ghost button with text reads as a label next to other text, not as a control; an inline or row action is IconButton with a Tooltip. A ghost TEXT button still fits a dialog's own primary/secondary action row."
+  },
+  {
+    id: "popover-fixed-rem-width",
+    // A `width` written in rem (or calc of rem) on a Popover: the shape DX-5257 made unnecessary.
+    pattern: new RegExp(r("Popover", "width", `[^"']*rem[^"']*`)),
+    preferInstead: ["Popover"],
+    reason: "a Popover with a hard-coded rem width makes a short list as wide as the cap. A Popover with no `width` sizes to its content up to 40rem and never past the viewport; pass `width` only for a panel that must be an exact size. DX-5257."
+  },
+  {
+    id: "bare-sort-icon-button",
+    // The semantic icon key a consumer draws a sort control with. A lone sort icon over a list of one-order-per-row radio
+    // items, which cannot show its direction, is the shape SortMenu replaces (DX-4312); SortMenu's own trigger is icon-only (DX-4378).
+    pattern: /["']action\.sort["']/,
+    preferInstead: ["SortMenu"],
+    reason: "a hand-built sort icon button that opens one radio row per order and shows no direction. SortMenu is the icon-only sort control: its trigger draws the arrow of the CURRENT direction (never text), its tooltip names the field and direction, and its popover lists each FIELD once with its own up and down arrow. A list whose orders are opaque single choices with no field/direction pair (a priority order, a relevance order) is the case a UI-LIBRARY-ALLOW reason covers. DX-4312, DX-4378."
+  },
+  {
+    id: "select-filter-stack",
+    // Three shapes, each one a list filter drawn by hand: a Select (or StatusSelect / Combobox / MultiSelect) whose accessible name says it
+    // is a filter (`aria-label="Filter by status"`, `aria-label={t("...filter.status")}`); a component DECLARED or USED under a name
+    // that says it is a select-shaped filter (`FilterSelect`, `StatusFilterDropdown`, `SelectFilter`); and nothing looser, because
+    // `isFilterSelected` or a prose mention of a filter is not a filter control.
+    pattern: new RegExp(
+      String.raw`<(?:Status|Multi)?(?:Select|Combobox)\b${a}*?\saria-label\s*=\s*\{?\s*(?:\w+\()?["'][^"']*[Ff]ilter` + "|" + String.raw`(?:<|\b(?:function|const|class)\s+)(?=[A-Z])\w*?(?:Filter(?:Select|Dropdown)|(?:Select|Dropdown)Filter)(?![a-z])`
+    ),
+    preferInstead: ["FilterMenu", "FilterChips"],
+    reason: 'a Select (or a select-shaped component) drawn as a list filter, which in practice means a row or stack of full-width dropdowns above a list that all read "Select...", hide what is applied inside each closed box and cannot hold two values of one filter. FilterMenu is the one filter control, and it draws EVERY kind of list filter, so no filter stays loose beside it: an icon button (with the count of filters on) that opens a popover with one labelled control per filter - toggle chips for a closed set (kind single or multiple, each option able to carry an icon and a colour tone), a searchable list for a long set (searchable), a switch for an on/off filter (boolean), From and To boxes for dates (date-range) and a text box for a typed value (text) - plus Clear all; FilterChips draws what is applied as removable chips under the row. Put it in the search + filters + sort row. A Select that picks a value to EDIT or CREATE something (not to narrow a list) is the case a UI-LIBRARY-ALLOW reason covers. DX-5374.'
+  },
+  {
+    id: "hand-rolled-attention",
+    // `animate-ping` is Tailwind's expanding-and-fading ring, and the one thing it is used for by hand is
+    // "look here": a ping span stacked behind a control. Matched as a class token, so `animate-ping-slow` and
+    // a prose mention inside a longer word do not count.
+    pattern: new RegExp("(?<![\\w-])animate-ping(?![\\w-])"),
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["Attention", "Badge"],
+    reason: "a hand-stacked animate-ping span. To draw the eye to a control, Attention wraps any control and draws it for you: slow click-ripple circles that grow from the centre and fade out, each to a different radius (or a pulse, glow, travelling ring, beacon, shimmer, bounce or wiggle) in the library's semantic tones, on a circle, pill, rounded, square or inherited shape, with no layout shift, a static highlight under reduced motion, and a graceful stop. Use it only while something is waiting for the viewer. A pinging live-status dot (running, connected, streaming) is not that: it is Badge with dot and pulse. DX-4494."
+  },
+  {
+    id: "emoji-rating-row",
+    // Two or more mood-face emoji on one line: the radio row of emoji a hand-built "how was it" scale is made of.
+    pattern: /(?:[\u{1F620}\u{1F621}\u{1F61E}\u{1F61F}\u{1F641}\u{2639}\u{1F610}\u{1F611}\u{1F642}\u{1F60A}\u{1F600}\u{1F603}\u{1F604}\u{1F601}]\u{FE0F}?[^\n]{0,40}){2,}/u,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["RatingScale", "RatingFace"],
+    reason: "a hand-built row of mood-face emoji. RatingScale is the five-face scale (very unhappy to very happy) as a radio group: one tab stop, arrows move and select, each face named and with a tooltip, the chosen face tone-coloured from red to green, optionally clearable. RatingFace is its read-only single face for a table or list. Emoji render differently on every platform and are not icons (the dashboard rule). DX-5235."
+  },
+  {
+    id: "hand-rolled-infinite-scroll",
+    // Two shapes, one rule. A virtual-list or infinite-scroll package import is the obvious one. The other is a file that
+    // watches a sentinel with an IntersectionObserver AND fetches "the next page" — the hand-built version. Both are
+    // anchored at the start of the file with lookaheads, so matching stays linear however long the file is.
+    pattern: /from\s+["'](?:react-infinite-scroll-component|react-infinite-scroller|react-window(?:-infinite-loader)?|react-virtuoso|react-virtualized|@tanstack\/react-virtual)["']|^(?=[\s\S]*\bIntersectionObserver\b)(?=[\s\S]*\b(?:loadMore|fetchNextPage|loadNextPage|hasNextPage|nextPage)\b)/,
+    preferInstead: ["PagedWindowList", "usePagedWindow"],
+    reason: "a hand-built infinite or virtualised list. PagedWindowList (with usePagedWindow) holds a window of pages of a long server-side list — the page in view plus one on each side, 60 cards at 20 a page, everything else dropped from memory and replaced by a placeholder of the right height — so the scrollbar spans the whole total and can be dragged anywhere (the window moves only once the viewer has stopped for 200 ms, so a fast sweep reads the pages where it lands and not the ones it passes, and a read for a page that left the window is aborted through its signal), a page is read again in place when a card changes, and the window freezes while a drag is live so a board's drag-and-drop keeps working on the cards that are rendered. It drops into a BoardColumn as its children and reports the viewer's position through IntersectionObserver, never a scroll listener. A feed that only ever appends and never needs to jump or drop what it loaded is the case a UI-LIBRARY-ALLOW reason covers. DX-4540."
+  },
+  {
+    id: "hand-rolled-sortable-list",
+    // An import from a drag-and-drop or sortable-list package: the shape a hand-built reorderable list takes. The library's own
+    // DragDrop is what OrderedEntityManager is built on, so nothing needs a second drag dependency.
+    pattern: /from\s+["'](?:@dnd-kit\/[\w-]+|react-beautiful-dnd|@hello-pangea\/dnd|react-sortablejs|sortablejs|react-sortable-hoc|react-dnd|@atlaskit\/pragmatic-drag-and-drop(?:\/[\w-]+)*)["']/,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["OrderedEntityManager"],
+    reason: "a hand-built reorderable list. OrderedEntityManager is the ordered list manager: entries a person adds, renames in place, deletes behind a confirm and reorders by drag handle or keyboard (Space to pick up, arrows to move, Space to drop), with an optional colour and emoji per entry edited in place (ColorPicker, the one colour control, with the caller's palette as colorPicker.presets, and EmojiPicker, configured through emojiPicker), a row that can be locked in place (a running queue item), one highlighted entry (the item just added) and a read-only badge per entry (a queue item's state). It is controlled: pass the entries and handle onReorder, onRename, onDelete, onCreate, onChangeColor and onChangeEmoji, and it saves nothing itself; each control appears only when its handler is passed, so a list that only reorders passes onReorder. A list that is not a flat, person-ordered list of named entries (a board of cards, a tree) is the case a UI-LIBRARY-ALLOW reason covers; Board and Kanban own card moves. DXUI-27."
+  },
+  {
+    id: "hand-rolled-color-picker",
+    // A colour-picker package: the shape a hand-built swatch chooser takes. A native type="color" input is `native-colour-input`'s.
+    pattern: /from\s+["'](?:react-colorful|react-color|@uiw\/react-color(?:-[\w-]+)?|vue-color)["']/,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["ColorPicker"],
+    reason: "a hand-built colour chooser. ColorPicker is the one colour control: a swatch button that opens a saturation/brightness area, a hue slider, a #rrggbb hex field and optional preset swatches (the caller's own palette, with the stored one marked), controlled (value in, onChange out). Use it for any colour value, a fixed palette included (pass it as presets); OrderedEntityManager uses it for a list entry's colour. DXUI-27, DXUI-28."
+  },
+  {
+    id: "hand-rolled-emoji-picker",
+    // An emoji-picker package: the shape a hand-built emoji chooser takes.
+    pattern: /from\s+["'](?:emoji-picker-react|emoji-picker-element|@emoji-mart\/react|emoji-mart|rn-emoji-keyboard|react-emoji-picker)["']/,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["EmojiPicker"],
+    reason: "a hand-built emoji chooser. EmojiPicker is a trigger showing the current emoji that opens a grid of choices and a field for any other value, controlled (value in, onChange out) and one Tab stop with arrow keys between choices. The stored value is the caller's: pass options as { value, glyph, label } to store a Slack emoji name such as gear while the trigger and grid show the glyph, with validateCustom for a typed value (default: exactly one Unicode emoji), renderValue for a stored value outside the options, allowCustom to close the set, searchable to add a search box over a large set (about 1,900 names stay cheap: at most 160 matches are drawn) and clearable={false} to make the emoji required. OrderedEntityManager uses it for a list entry's emoji. DXUI-27."
+  },
+  {
+    id: "hand-rolled-diff",
+    pattern: /from\s+["'](?:diff|diff-match-patch|jsdiff)["']/,
+    preferInstead: ["LineDiff", "PatchDiff"],
+    reason: "a diff computed by hand and rendered as custom markup; LineDiff compares a value against its baseline line by line, and PatchDiff draws a file's unified-diff patch (a pull request's changed file) with hunk line numbers and a collapsible header, both with the tone tokens and dark mode already handled. DX-3787, DX-5271."
+  },
+  {
+    id: "hand-built-time-series",
+    // An import from a charting package: the shape a hand-picked time series takes. TimeSeriesChart
+    // takes the same buckets, and LineChart the same instants, so nothing needs a second charting
+    // dependency (DX-4328, DX-4933).
+    pattern: /from\s+["'](?:recharts|chart\.js(?:\/[\w-]+)*|react-chartjs-2|d3(?:-[\w-]+)?|victory|@visx\/[\w-]+|@nivo\/[\w-]+|apexcharts|react-apexcharts|echarts(?:-for-react)?)["']/,
+    preferInstead: ["TimeSeriesChart", "LineChart"],
+    reason: `a charting package imported to draw values over time. Which one depends on the question. TimeSeriesChart answers "how much, per span, and by what": stacked columns (or areas) over time buckets the caller has already summed, in the library's chart palette, with a hatched block for unmeasured spans; the stack is a total, so use it only for values that add up (tokens, dollars). LineChart answers "what was it at this moment": one non-stacked line per series over points at real timestamps, horizontal reference lines (a limit, a budget) and markers on a series at an instant (an event, with caller content on hover and focus); use it for a level that does not add across series, such as a context size. Both have a time axis, a zero-based value axis, a tooltip on hover and keyboard focus, a toggling legend, deliberate empty states and a hidden table, and neither adds a dependency. DX-4328, DX-4933.`
+  },
+  {
+    id: "hand-built-bar",
+    // A `style` prop that sizes an element by a PERCENTAGE width — the shape every hand-built
+    // bar takes (`style={{ width: `${pct}%` }}`, `width: pct + "%"`, `width: "40%"`). The
+    // value is read through the brace depth PROP_UNIT already understands, and the `%` must
+    // sit in a string/template/concatenation, so `width: 100` or `width: px` never match.
+    pattern: /\bstyle\s*=\s*\{\{[^{}]*\bwidth\s*:\s*(?:`[^`]*%[^`]*`|"[^"]*%"|'[^']*%'|[^,}]*\+\s*["']%["'])/,
+    preferInstead: ["ShareBar", "BarList"],
+    reason: "a div sized by a percentage width is a hand-built bar. A whole divided into parts is ShareBar (one 100% bar, a legend, direct % labels, a tooltip and a table view); a ranked list of values is BarList (one sequential hue, a label and value per row). Both draw from the library's categorical chart palette with the contrast checked in light, dark and high-contrast, and give every mark a text equivalent. A single task or quota is Progress / Meter; a gauge that can sit at empty and should look it is a Meter with `emptyTrack` set to 'dashed'; a quota with a target or budget to stay under is a Meter with `marker` (a tick at the target, `markerLabel` describing it) and `overflowTone`, which draws what runs past the target in a second tone on a track stretched to hold it (marker 0 means start nothing). DX-3963, DX-5243."
+  },
+  {
+    id: "hand-built-step-rail",
+    // `aria-current="step"` is the attribute a hand-built step strip puts on its current marker: the library's Stepper already
+    // sets it, so a consumer file that writes it itself is drawing the rail by hand.
+    pattern: /\baria-current\s*=\s*(?:"step"|'step'|\{\s*(?:"step"|'step')\s*\})/,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["Stepper"],
+    reason: 'a hand-built step strip. Stepper is the guided sequence: a rail with a position ("Step 3 of 9"), the gate on the way forward with its reason beside the control, and a status per step that is more than done or not done: complete (green tick), skipped (a grey dash, for a step the person passed on purpose, set with `skipped: true`, counted in a neutral chip and never mistaken for a failure), unverified (a grey ringed dot, for a step that is done but has nothing a server can test, set with `unverified: "Saved, not tested"`, its words printed and spoken, counted in no chip), incomplete (red cross, passed over by accident), failed (a red ringed exclamation for a step whose server check refused it, set with `failed: "Asana refused the token"`, the reason printed and spoken, outranking every other state; never draw a refusal with `blocked`, which is amber and means cannot start yet), blocked and upcoming. It stays readable with many steps (labels wrap and the strip scrolls; `orientation="side"` puts the rail beside the content from 1024px; `compact` or `compact="auto"` folds it, wherever the rail does not fit (below 1024px with the side rail), to "Step 3 of 9: Project" with a button for the full list on a phone). Mark a step you want to show as left on purpose `skipped`, never `complete` (false) and never left incomplete (a red cross reads as a failure). DX-4963.'
+  },
+  {
+    id: "hand-built-toggle-grid",
+    // A file that lays out a raw <table> AND puts a checkbox, switch or toggle cell in it: the shape of a hand-built rows-by-columns
+    // on/off grid (a permissions matrix, a "what syncs" grid). Anchored at the start of the file with lookaheads, so matching stays linear.
+    pattern: /^(?=[\s\S]*<table\b)(?=[\s\S]*(?:role\s*=\s*["']checkbox["']|<Checkbox\b|<Switch\b|<Toggle\b))/,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["ToggleMatrix"],
+    reason: "a hand-built grid of on/off cells. ToggleMatrix is the one generic rows-by-columns matrix (RolePermissionMatrix is an adapter over it): rows with a label and a description, columns with a label, and a cell that is on, off or unavailable with a reason printed IN the cell (readable on a phone, no hover), a header checkbox that sets a whole column (checked, mixed, disabled), a read-only mode, a lock on a column that cannot be edited, a busy spinner per cell, group headings, and headers aligned over their cells down to 390px wide. A DataTable with a Checkbox in each cell is the same hand-built grid and loses the column control and the aligned headers. A table of records that merely has a selection checkbox is the case a UI-LIBRARY-ALLOW reason covers. DX-4963."
+  },
+  {
+    id: "setting-row-long-value-inline",
+    // A SettingRow whose own props hold a CopyValue as the control and no `layout` prop: the long value sits beside the text. The
+    // negative lookahead scans the same opening tag the match does, so the rule stays inside one tag.
+    pattern: new RegExp(
+      String.raw`<SettingRow\b(?!${a}*?\slayout\s*=)${a}*?\scontrol\s*=\s*\{\s*<CopyValue\b`
+    ),
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ['SettingRow layout="stacked"'],
+    reason: 'a copyable URL or token in a SettingRow control is laid out beside the label from 640px up, and a value box that cannot shrink takes the whole row: the label and description wrap one word per line, or the box runs past the card edge with its copy button out of view. SettingRow takes layout="stacked": label and description on top, the control full width under them at every width, so CopyValue truncates inside its box with the copy button always visible. Use it for any control that holds a long value to read or copy. DX-4968.'
+  },
+  // ---- DX-5567: a keyword search box has its clear (x) inside it.
+  {
+    id: "bare-search-input",
+    pattern: new RegExp(r("Input", "type", "search")),
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["SearchInput"],
+    reason: 'an Input with type="search" drawn as a keyword search box. SearchInput is the one search box: the search icon at its leading edge and, only while it holds text, a "Clear search" x button inside the field at its trailing edge that empties the value and returns focus to the box (the browsers own clear glyph is suppressed so only this one shows). Hosts pass `value` and `onValueChange(value)`; a list that applies on Enter or blur also commits when the value is emptied. A search that must not carry a clear button is the case a UI-LIBRARY-ALLOW reason covers. DX-5567.'
+  },
+  // ---- DX-4985: a stored secret is shown, never an input. Three shapes of the old way, one rule each.
+  {
+    id: "bare-password-input-for-secret",
+    pattern: new RegExp(r("Input", "type", "password")),
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["SecretField"],
+    reason: `an Input with type="password" over a credential. A SECRET THAT CAN BE STORED is never an input while it is stored: SecretField draws the masked value with its first and last characters, a status from a real test of the secret (verified, failed with the provider's reason, unverifiable, not checked), a Re-verify button and Clear, and the input only when nothing is stored or after Clear. Replacing is Clear, then paste. A password the person is choosing or typing to sign in is PasswordInput; this rule is for a credential the app keeps. DX-4985.`
+  },
+  {
+    id: "local-secret-row",
+    // The old app wrapper by its name (declared or used), and any local Secret/Credential/Token/ApiKey Row/Field/Input component
+    // declared in app code: they exist to draw an input over a stored secret.
+    pattern: /<SecretRow\b|\b(?:function|const)\s+(?:Secret|Credential|Token|ApiKey)\w*(?:Row|Field|Input)\b/,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["SecretField"],
+    reason: 'a local wrapper that draws a stored secret (a "SecretRow": a password box that says "Saved and hidden. Paste a new value to replace it."). That is the shape the stored-secret rule retired: an input over a working credential invites pasting over it and says nothing about whether it works. SecretField is the one component: no input while stored, masked ends, status icon and words, Re-verify, Clear (staged inside a batch-save form with `clear="staged"`, at once in a row with `clear="immediate"`). Delete the wrapper and pass SecretField the server\'s hint, status and updated-by. DX-4985.'
+  },
+  {
+    id: "hand-built-masked-secret",
+    // A string that is nothing but dots: the placeholder or display a stored secret is hidden behind.
+    pattern: /["'`]•{4,}["'`]/,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["SecretField"],
+    reason: 'a hand-made run of dots standing in for a stored secret (a placeholder over a password box, or a masked token drawn by hand). SecretField draws the stored face itself: the first and last characters from `hint` around a fixed mask, so no screen invents its own mask, its own badge or its own "Check again". DX-4985.'
+  },
+  {
+    id: "secret-field-without-status",
+    // A SecretField opening tag with no `status` prop, scanned inside the one tag. A secret the app keeps is tested, and "not testable"
+    // is still a status the caller words (`{ kind: "unverifiable", message }`).
+    pattern: new RegExp(String.raw`<SecretField\b(?:(?!\sstatus\b)${a})*\/?>`),
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["SecretField status={...} onVerify={...}"],
+    reason: 'a SecretField with no `status`. Without one the stored face reads "Not checked" for ever, which hides whether the credential works. Pass the server\'s result of testing it (`verified`, `failed` with the provider\'s reason, `checking`, `unchecked`) plus `onVerify` for the Re-verify button, or `{ kind: "unverifiable", message }` with the reason nothing can test it (an OAuth client secret). A SecretField that only ever shows a secret once, at creation (nothing stored), is the case a UI-LIBRARY-ALLOW reason covers. DX-4985.'
+  },
+  // ---- DXUI-28: a colour value is picked with ColorPicker.
+  {
+    id: "native-colour-input",
+    pattern: /\stype\s*=\s*(?:"color"|'color'|\{\s*(?:"color"|'color')\s*\})/,
+    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text
+    preferInstead: ["ColorPicker"],
+    reason: 'an input of type="color". The browser draws its own picker, different on every platform and outside the theme. ColorPicker is the one colour control: a swatch button that opens a saturation/brightness area, a hue slider, a #rrggbb hex field that shows a bad value as a field error, and optional preset swatches; it works from the keyboard, and `onChange` fires with the committed colour on release rather than on every pointer move. Use it for any colour value. DXUI-28.'
+  }
+];
+export {
+  d as COMPONENT_GUIDANCE
+};
+//# sourceMappingURL=component-guidance.js.map

package/dist/lib/component-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-guidance.js","sources":["../../src/lib/component-guidance.ts"],"sourcesContent":["/* ============================================================================\n   COMPONENT GUIDANCE — the library's own \"richer alternative\" map. DX-3789.\n\n   WHY THIS IS DATA, NOT A DOCUMENT.\n\n   Every consuming repo used to keep its OWN hand-written list of \"if you see\n   X, use Y instead\" (a hard-coded regex table in a source-scan test). That\n   list drifted from this library on day one: a new richer component here\n   (`InlineMarkdownEdit`, `IconButton`) did nothing for a consumer's\n   enforcement until someone remembered to go update a table in a DIFFERENT\n   repo by hand. The library is the one place that knows its own component\n   set, so the library is the one place this map can live without drifting.\n\n   THE ONE PRINCIPLE THIS DATA ENFORCES: for each piece of data a UI renders,\n   use the MOST CAPABLE `@50arms/ui` component that fits it. Inline editing\n   in place is the default interaction — never a read view plus a separate\n   edit box or dialog for an existing value. Choosing a plainer primitive\n   where a richer one fits is sometimes correct (a short label really is a\n   `Textarea`-free `InlineEdit`; a `Button` really does belong ghost-styled\n   inside a `Dialog`'s own action row) — that is exactly what a consumer's\n   `UI-LIBRARY-ALLOW: <reason>` escape hatch is for. This map only says which\n   substitutions are usually right; it does not forbid the exception.\n\n   Each rule's `pattern` is matched against a WHOLE FILE's text (not a single\n   line — `lineMode=\"multiline\"` and `variant=\"ghost\"` routinely land on a\n   prop line different from the opening tag), so a consumer's scanner reports\n   the FIRST matching line for its message rather than re-deriving one here.\n\n   A rule fires on the SUPERSEDED shape; `preferInstead` names what a consumer\n   should reach for. `raw:*` ids are the native-HTML-element/ARIA-role half of\n   this table — DX-3789 folded those into the same mechanism a consumer used\n   to hard-code separately, so a new richer component added here extends every\n   consumer's enforcement with no repo edit on their side.\n   ============================================================================ */\n\nexport interface ComponentGuidanceRule {\n  /** Stable id — used only for messages/tooling, never matched against. */\n  id: string;\n  /** Tested against a whole file's source text. Deliberately case-sensitive\n   *  (see `raw-*` rules below) — a lowercase native tag is the violation; the\n   *  identically-spelled PascalCase `@50arms/ui` export is not. */\n  pattern: RegExp;\n  /** The component(s) that usually fit better than the matched shape. */\n  preferInstead: readonly string[];\n  /** Why the richer alternative usually fits — surfaced in a consumer's\n   *  violation message, and what a `UI-LIBRARY-ALLOW: <reason>` comment is\n   *  answering when the richer one genuinely does not apply here. */\n  reason: string;\n}\n\n/* ----------------------------------------------------------------------------\n   JSX OPENING-TAG PROPS, AS A REGEX (DX-3789 round 2).\n\n   A rule that reads \"this component, with that prop\" has to stay inside ONE\n   opening tag and understand what a prop value can contain. The first version\n   used `(?:[^>]|\\n)*?` between the tag name and the prop, and that failed three\n   ways on real code: an arrow function (`onClick={() => go()}`) ended the match\n   at its own `>` (so a prop after it was missed), the same `>` after the prop\n   made a SELF-CLOSING tag look like it had text children (a false positive),\n   and the overlapping `[^>]|\\n` alternation backtracked exponentially on every\n   newline (26 lines took ~500 ms).\n\n   `PROP_UNIT` is one step of a tag's props, and its four alternatives start\n   with four DISJOINT characters, so the engine has exactly one way to read any\n   prop run and cannot backtrack exponentially:\n     - a plain character that is none of `>` `{` `}` `\"` `'` `/` (names, `=`,\n       whitespace). `/` is excluded on purpose: the only `/` outside a value is\n       the `/>` of a self-closing tag, so such a tag simply fails to match;\n     - a quoted attribute string (may span lines);\n     - a `{...}` expression, with strings and nested braces understood to depth\n       three (`style={{ a: { b: 1 } }}`), so a `>` inside it never ends the tag.\n   A `{...}` whose own strings are unterminated on their line (an apostrophe in\n   JSX text inside the expression) fails to match: an under-count, never a hang.\n   ---------------------------------------------------------------------------- */\nconst EXPR_STRING = String.raw`\"[^\"\\n]*\"|'[^'\\n]*'|\\`[^\\`]*\\``;\n\nfunction braceGroup(depth: number): string {\n  const nested = depth > 1 ? `|${braceGroup(depth - 1)}` : \"\";\n  return String.raw`\\{(?:[^{}\"'\\`]|${EXPR_STRING}${nested})*\\}`;\n}\n\nconst PROP_UNIT = String.raw`(?:[^>{}\"'/]|\"[^\"]*\"|'[^']*'|${braceGroup(3)})`;\n\n/** `name=\"value\"`, `name='value'` or `name={\"value\"}`, as a whole attribute. */\nfunction attr(name: string, value: string): string {\n  return String.raw`\\s${name}\\s*=\\s*(?:\"${value}\"|'${value}'|\\{\\s*(?:\"${value}\"|'${value}')\\s*\\})`;\n}\n\n/** `<Tag` ... up to and including the attribute, all inside one opening tag. */\nfunction tagWithAttr(tag: string, name: string, value: string): string {\n  return String.raw`<${tag}\\b${PROP_UNIT}*?${attr(name, value)}`;\n}\n\nexport const COMPONENT_GUIDANCE: readonly ComponentGuidanceRule[] = [\n  // ---- native HTML / raw ARIA — always wrong; the library owns these shapes.\n  {\n    id: \"raw-button\",\n    pattern: /<button\\b/,\n    preferInstead: [\"Button\"],\n    reason: 'a native <button> — the library\\'s Button carries focus, hover and disabled states the raw element does not.',\n  },\n  {\n    id: \"raw-video\",\n    pattern: /<video\\b/,\n    preferInstead: [\"VideoPlayer\"],\n    reason: \"a native <video> — VideoPlayer carries the accessible name, preload=metadata, caption tracks and the can't-play fallback a raw element lacks (and FileCover is the fixed-size cover for a file that may be a video). DX-3982.\",\n  },\n  {\n    id: \"raw-input\",\n    pattern: /<input\\b/,\n    preferInstead: [\"Input\"],\n    reason: \"a native <input> — use the library's Input.\",\n  },\n  {\n    id: \"raw-select\",\n    pattern: /<select\\b/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"Select\", \"Combobox\"],\n    reason: \"a native <select> — use the library's Select (or Combobox for a searchable list).\",\n  },\n  {\n    id: \"raw-textarea\",\n    pattern: /<textarea\\b/,\n    preferInstead: [\"Textarea\"],\n    reason: \"a native <textarea> — use the library's Textarea (or see textarea-for-prose if this holds human-written text).\",\n  },\n  {\n    id: \"raw-dialog\",\n    pattern: /<dialog\\b/,\n    preferInstead: [\"Dialog\"],\n    reason: \"a native <dialog> — use the library's Dialog.\",\n  },\n  {\n    id: \"raw-pre\",\n    pattern: /<pre\\b/,\n    preferInstead: [\"Markdown\"],\n    reason: \"<pre> renders literal text; prose or a human-written document is markdown and should render through Markdown. Real code or log output is the one case <pre> still fits.\",\n  },\n  {\n    id: \"raw-clipboard-write\",\n    pattern: /navigator\\.clipboard\\.writeText\\s*\\(/,\n    preferInstead: [\"CopyValue\", \"copyText\"],\n    reason: \"a raw navigator.clipboard.writeText is refused in some in-app browsers and has no outcome shown — CopyValue is a value with its one-click copy and an announced result; copyText is the same copy with the execCommand fallback when you need the act without the control.\",\n  },\n  {\n    id: \"role-menu\",\n    pattern: /role\\s*=\\s*[\"']menu[\"']/,\n    preferInstead: [\"Menu\"],\n    reason: 'a hand-rolled role=\"menu\" — use Menu, which owns focus and keyboard navigation for you.',\n  },\n  {\n    id: \"role-listbox\",\n    pattern: /role\\s*=\\s*[\"']listbox[\"']/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"Combobox\", \"Select\"],\n    reason: 'a hand-rolled role=\"listbox\" — use Combobox (searchable) or Select.',\n  },\n  {\n    id: \"role-dialog\",\n    pattern: /role\\s*=\\s*[\"']dialog[\"']/,\n    preferInstead: [\"Dialog\"],\n    reason: 'a hand-rolled role=\"dialog\" — use Dialog, which owns focus trapping and dismissal for you.',\n  },\n  {\n    id: \"role-tab\",\n    pattern: /role\\s*=\\s*[\"']tab[\"']/,\n    preferInstead: [\"Tabs\"],\n    reason: 'a hand-rolled role=\"tab\" — use Tabs.',\n  },\n  // ---- basic @50arms/ui primitive superseded by a richer one for its case.\n  {\n    id: \"textarea-for-prose\",\n    pattern: /<Textarea\\b/,\n    preferInstead: [\"InlineMarkdownEdit\", \"MarkdownEditor\"],\n    reason: \"Textarea holds plain text; multi-line human-written prose is markdown and belongs in InlineMarkdownEdit (read in place, edited in place) or MarkdownEditor.\",\n  },\n  {\n    id: \"inline-edit-multiline\",\n    pattern: new RegExp(tagWithAttr(\"InlineEdit\", \"lineMode\", \"multiline\")),\n    preferInstead: [\"InlineMarkdownEdit\"],\n    reason: \"a multiline InlineEdit holds prose; InlineMarkdownEdit renders and edits it as markdown in the same place.\",\n  },\n  {\n    id: \"ghost-text-button\",\n    // The attribute, the rest of the SAME opening tag, its closing `>` (a `/>`\n    // self-closing tag cannot match), then a first child that is text.\n    pattern: new RegExp(`${tagWithAttr(\"Button\", \"variant\", \"ghost\")}${PROP_UNIT}*>\\\\s*[^\\\\s<{]`),\n    preferInstead: [\"IconButton\"],\n    reason: \"a ghost button with text reads as a label next to other text, not as a control; an inline or row action is IconButton with a Tooltip. A ghost TEXT button still fits a dialog's own primary/secondary action row.\",\n  },\n  {\n    id: \"popover-fixed-rem-width\",\n    // A `width` written in rem (or calc of rem) on a Popover: the shape DX-5257 made unnecessary.\n    pattern: new RegExp(tagWithAttr(\"Popover\", \"width\", `[^\"']*rem[^\"']*`)),\n    preferInstead: [\"Popover\"],\n    reason: \"a Popover with a hard-coded rem width makes a short list as wide as the cap. A Popover with no `width` sizes to its content up to 40rem and never past the viewport; pass `width` only for a panel that must be an exact size. DX-5257.\",\n  },\n  {\n    id: \"bare-sort-icon-button\",\n    // The semantic icon key a consumer draws a sort control with. A lone sort icon over a list of one-order-per-row radio\n    // items, which cannot show its direction, is the shape SortMenu replaces (DX-4312); SortMenu's own trigger is icon-only (DX-4378).\n    pattern: /[\"']action\\.sort[\"']/,\n    preferInstead: [\"SortMenu\"],\n    reason: \"a hand-built sort icon button that opens one radio row per order and shows no direction. SortMenu is the icon-only sort control: its trigger draws the arrow of the CURRENT direction (never text), its tooltip names the field and direction, and its popover lists each FIELD once with its own up and down arrow. A list whose orders are opaque single choices with no field/direction pair (a priority order, a relevance order) is the case a UI-LIBRARY-ALLOW reason covers. DX-4312, DX-4378.\",\n  },\n  {\n    id: \"select-filter-stack\",\n    // Three shapes, each one a list filter drawn by hand: a Select (or StatusSelect / Combobox / MultiSelect) whose accessible name says it\n    // is a filter (`aria-label=\"Filter by status\"`, `aria-label={t(\"...filter.status\")}`); a component DECLARED or USED under a name\n    // that says it is a select-shaped filter (`FilterSelect`, `StatusFilterDropdown`, `SelectFilter`); and nothing looser, because\n    // `isFilterSelected` or a prose mention of a filter is not a filter control.\n    pattern: new RegExp(\n      String.raw`<(?:Status|Multi)?(?:Select|Combobox)\\b${PROP_UNIT}*?\\saria-label\\s*=\\s*\\{?\\s*(?:\\w+\\()?[\"'][^\"']*[Ff]ilter` +\n        \"|\" +\n        String.raw`(?:<|\\b(?:function|const|class)\\s+)(?=[A-Z])\\w*?(?:Filter(?:Select|Dropdown)|(?:Select|Dropdown)Filter)(?![a-z])`,\n    ),\n    preferInstead: [\"FilterMenu\", \"FilterChips\"],\n    reason: \"a Select (or a select-shaped component) drawn as a list filter, which in practice means a row or stack of full-width dropdowns above a list that all read \\\"Select...\\\", hide what is applied inside each closed box and cannot hold two values of one filter. FilterMenu is the one filter control, and it draws EVERY kind of list filter, so no filter stays loose beside it: an icon button (with the count of filters on) that opens a popover with one labelled control per filter - toggle chips for a closed set (kind single or multiple, each option able to carry an icon and a colour tone), a searchable list for a long set (searchable), a switch for an on/off filter (boolean), From and To boxes for dates (date-range) and a text box for a typed value (text) - plus Clear all; FilterChips draws what is applied as removable chips under the row. Put it in the search + filters + sort row. A Select that picks a value to EDIT or CREATE something (not to narrow a list) is the case a UI-LIBRARY-ALLOW reason covers. DX-5374.\",\n  },\n  {\n    id: \"hand-rolled-attention\",\n    // `animate-ping` is Tailwind's expanding-and-fading ring, and the one thing it is used for by hand is\n    // \"look here\": a ping span stacked behind a control. Matched as a class token, so `animate-ping-slow` and\n    // a prose mention inside a longer word do not count.\n    pattern: /(?<![\\w-])animate-ping(?![\\w-])/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"Attention\", \"Badge\"],\n    reason: \"a hand-stacked animate-ping span. To draw the eye to a control, Attention wraps any control and draws it for you: slow click-ripple circles that grow from the centre and fade out, each to a different radius (or a pulse, glow, travelling ring, beacon, shimmer, bounce or wiggle) in the library's semantic tones, on a circle, pill, rounded, square or inherited shape, with no layout shift, a static highlight under reduced motion, and a graceful stop. Use it only while something is waiting for the viewer. A pinging live-status dot (running, connected, streaming) is not that: it is Badge with dot and pulse. DX-4494.\",\n  },\n  {\n    id: \"emoji-rating-row\",\n    // Two or more mood-face emoji on one line: the radio row of emoji a hand-built \"how was it\" scale is made of.\n    pattern: /(?:[\\u{1F620}\\u{1F621}\\u{1F61E}\\u{1F61F}\\u{1F641}\\u{2639}\\u{1F610}\\u{1F611}\\u{1F642}\\u{1F60A}\\u{1F600}\\u{1F603}\\u{1F604}\\u{1F601}]\\u{FE0F}?[^\\n]{0,40}){2,}/u,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"RatingScale\", \"RatingFace\"],\n    reason: \"a hand-built row of mood-face emoji. RatingScale is the five-face scale (very unhappy to very happy) as a radio group: one tab stop, arrows move and select, each face named and with a tooltip, the chosen face tone-coloured from red to green, optionally clearable. RatingFace is its read-only single face for a table or list. Emoji render differently on every platform and are not icons (the dashboard rule). DX-5235.\",\n  },\n  {\n    id: \"hand-rolled-infinite-scroll\",\n    // Two shapes, one rule. A virtual-list or infinite-scroll package import is the obvious one. The other is a file that\n    // watches a sentinel with an IntersectionObserver AND fetches \"the next page\" — the hand-built version. Both are\n    // anchored at the start of the file with lookaheads, so matching stays linear however long the file is.\n    pattern: /from\\s+[\"'](?:react-infinite-scroll-component|react-infinite-scroller|react-window(?:-infinite-loader)?|react-virtuoso|react-virtualized|@tanstack\\/react-virtual)[\"']|^(?=[\\s\\S]*\\bIntersectionObserver\\b)(?=[\\s\\S]*\\b(?:loadMore|fetchNextPage|loadNextPage|hasNextPage|nextPage)\\b)/,\n    preferInstead: [\"PagedWindowList\", \"usePagedWindow\"],\n    reason: \"a hand-built infinite or virtualised list. PagedWindowList (with usePagedWindow) holds a window of pages of a long server-side list — the page in view plus one on each side, 60 cards at 20 a page, everything else dropped from memory and replaced by a placeholder of the right height — so the scrollbar spans the whole total and can be dragged anywhere (the window moves only once the viewer has stopped for 200 ms, so a fast sweep reads the pages where it lands and not the ones it passes, and a read for a page that left the window is aborted through its signal), a page is read again in place when a card changes, and the window freezes while a drag is live so a board's drag-and-drop keeps working on the cards that are rendered. It drops into a BoardColumn as its children and reports the viewer's position through IntersectionObserver, never a scroll listener. A feed that only ever appends and never needs to jump or drop what it loaded is the case a UI-LIBRARY-ALLOW reason covers. DX-4540.\",\n  },\n  {\n    id: \"hand-rolled-sortable-list\",\n    // An import from a drag-and-drop or sortable-list package: the shape a hand-built reorderable list takes. The library's own\n    // DragDrop is what OrderedEntityManager is built on, so nothing needs a second drag dependency.\n    pattern: /from\\s+[\"'](?:@dnd-kit\\/[\\w-]+|react-beautiful-dnd|@hello-pangea\\/dnd|react-sortablejs|sortablejs|react-sortable-hoc|react-dnd|@atlaskit\\/pragmatic-drag-and-drop(?:\\/[\\w-]+)*)[\"']/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"OrderedEntityManager\"],\n    reason: \"a hand-built reorderable list. OrderedEntityManager is the ordered list manager: entries a person adds, renames in place, deletes behind a confirm and reorders by drag handle or keyboard (Space to pick up, arrows to move, Space to drop), with an optional colour and emoji per entry edited in place (ColorPicker, the one colour control, with the caller's palette as colorPicker.presets, and EmojiPicker, configured through emojiPicker), a row that can be locked in place (a running queue item), one highlighted entry (the item just added) and a read-only badge per entry (a queue item's state). It is controlled: pass the entries and handle onReorder, onRename, onDelete, onCreate, onChangeColor and onChangeEmoji, and it saves nothing itself; each control appears only when its handler is passed, so a list that only reorders passes onReorder. A list that is not a flat, person-ordered list of named entries (a board of cards, a tree) is the case a UI-LIBRARY-ALLOW reason covers; Board and Kanban own card moves. DXUI-27.\",\n  },\n  {\n    id: \"hand-rolled-color-picker\",\n    // A colour-picker package: the shape a hand-built swatch chooser takes. A native type=\"color\" input is `native-colour-input`'s.\n    pattern: /from\\s+[\"'](?:react-colorful|react-color|@uiw\\/react-color(?:-[\\w-]+)?|vue-color)[\"']/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"ColorPicker\"],\n    reason: \"a hand-built colour chooser. ColorPicker is the one colour control: a swatch button that opens a saturation/brightness area, a hue slider, a #rrggbb hex field and optional preset swatches (the caller's own palette, with the stored one marked), controlled (value in, onChange out). Use it for any colour value, a fixed palette included (pass it as presets); OrderedEntityManager uses it for a list entry's colour. DXUI-27, DXUI-28.\",\n  },\n  {\n    id: \"hand-rolled-emoji-picker\",\n    // An emoji-picker package: the shape a hand-built emoji chooser takes.\n    pattern: /from\\s+[\"'](?:emoji-picker-react|emoji-picker-element|@emoji-mart\\/react|emoji-mart|rn-emoji-keyboard|react-emoji-picker)[\"']/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"EmojiPicker\"],\n    reason: \"a hand-built emoji chooser. EmojiPicker is a trigger showing the current emoji that opens a grid of choices and a field for any other value, controlled (value in, onChange out) and one Tab stop with arrow keys between choices. The stored value is the caller's: pass options as { value, glyph, label } to store a Slack emoji name such as gear while the trigger and grid show the glyph, with validateCustom for a typed value (default: exactly one Unicode emoji), renderValue for a stored value outside the options, allowCustom to close the set, searchable to add a search box over a large set (about 1,900 names stay cheap: at most 160 matches are drawn) and clearable={false} to make the emoji required. OrderedEntityManager uses it for a list entry's emoji. DXUI-27.\",\n  },\n  {\n    id: \"hand-rolled-diff\",\n    pattern: /from\\s+[\"'](?:diff|diff-match-patch|jsdiff)[\"']/,\n    preferInstead: [\"LineDiff\", \"PatchDiff\"],\n    reason: \"a diff computed by hand and rendered as custom markup; LineDiff compares a value against its baseline line by line, and PatchDiff draws a file's unified-diff patch (a pull request's changed file) with hunk line numbers and a collapsible header, both with the tone tokens and dark mode already handled. DX-3787, DX-5271.\",\n  },\n  {\n    id: \"hand-built-time-series\",\n    // An import from a charting package: the shape a hand-picked time series takes. TimeSeriesChart\n    // takes the same buckets, and LineChart the same instants, so nothing needs a second charting\n    // dependency (DX-4328, DX-4933).\n    pattern: /from\\s+[\"'](?:recharts|chart\\.js(?:\\/[\\w-]+)*|react-chartjs-2|d3(?:-[\\w-]+)?|victory|@visx\\/[\\w-]+|@nivo\\/[\\w-]+|apexcharts|react-apexcharts|echarts(?:-for-react)?)[\"']/,\n    preferInstead: [\"TimeSeriesChart\", \"LineChart\"],\n    reason: \"a charting package imported to draw values over time. Which one depends on the question. TimeSeriesChart answers \\\"how much, per span, and by what\\\": stacked columns (or areas) over time buckets the caller has already summed, in the library's chart palette, with a hatched block for unmeasured spans; the stack is a total, so use it only for values that add up (tokens, dollars). LineChart answers \\\"what was it at this moment\\\": one non-stacked line per series over points at real timestamps, horizontal reference lines (a limit, a budget) and markers on a series at an instant (an event, with caller content on hover and focus); use it for a level that does not add across series, such as a context size. Both have a time axis, a zero-based value axis, a tooltip on hover and keyboard focus, a toggling legend, deliberate empty states and a hidden table, and neither adds a dependency. DX-4328, DX-4933.\",\n  },\n  {\n    id: \"hand-built-bar\",\n    // A `style` prop that sizes an element by a PERCENTAGE width — the shape every hand-built\n    // bar takes (`style={{ width: `${pct}%` }}`, `width: pct + \"%\"`, `width: \"40%\"`). The\n    // value is read through the brace depth PROP_UNIT already understands, and the `%` must\n    // sit in a string/template/concatenation, so `width: 100` or `width: px` never match.\n    pattern: /\\bstyle\\s*=\\s*\\{\\{[^{}]*\\bwidth\\s*:\\s*(?:`[^`]*%[^`]*`|\"[^\"]*%\"|'[^']*%'|[^,}]*\\+\\s*[\"']%[\"'])/,\n    preferInstead: [\"ShareBar\", \"BarList\"],\n    reason: \"a div sized by a percentage width is a hand-built bar. A whole divided into parts is ShareBar (one 100% bar, a legend, direct % labels, a tooltip and a table view); a ranked list of values is BarList (one sequential hue, a label and value per row). Both draw from the library's categorical chart palette with the contrast checked in light, dark and high-contrast, and give every mark a text equivalent. A single task or quota is Progress / Meter; a gauge that can sit at empty and should look it is a Meter with `emptyTrack` set to 'dashed'; a quota with a target or budget to stay under is a Meter with `marker` (a tick at the target, `markerLabel` describing it) and `overflowTone`, which draws what runs past the target in a second tone on a track stretched to hold it (marker 0 means start nothing). DX-3963, DX-5243.\",\n  },\n  {\n    id: \"hand-built-step-rail\",\n    // `aria-current=\"step\"` is the attribute a hand-built step strip puts on its current marker: the library's Stepper already\n    // sets it, so a consumer file that writes it itself is drawing the rail by hand.\n    pattern: /\\baria-current\\s*=\\s*(?:\"step\"|'step'|\\{\\s*(?:\"step\"|'step')\\s*\\})/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"Stepper\"],\n    reason: \"a hand-built step strip. Stepper is the guided sequence: a rail with a position (\\\"Step 3 of 9\\\"), the gate on the way forward with its reason beside the control, and a status per step that is more than done or not done: complete (green tick), skipped (a grey dash, for a step the person passed on purpose, set with `skipped: true`, counted in a neutral chip and never mistaken for a failure), unverified (a grey ringed dot, for a step that is done but has nothing a server can test, set with `unverified: \\\"Saved, not tested\\\"`, its words printed and spoken, counted in no chip), incomplete (red cross, passed over by accident), failed (a red ringed exclamation for a step whose server check refused it, set with `failed: \\\"Asana refused the token\\\"`, the reason printed and spoken, outranking every other state; never draw a refusal with `blocked`, which is amber and means cannot start yet), blocked and upcoming. It stays readable with many steps (labels wrap and the strip scrolls; `orientation=\\\"side\\\"` puts the rail beside the content from 1024px; `compact` or `compact=\\\"auto\\\"` folds it, wherever the rail does not fit (below 1024px with the side rail), to \\\"Step 3 of 9: Project\\\" with a button for the full list on a phone). Mark a step you want to show as left on purpose `skipped`, never `complete` (false) and never left incomplete (a red cross reads as a failure). DX-4963.\",\n  },\n  {\n    id: \"hand-built-toggle-grid\",\n    // A file that lays out a raw <table> AND puts a checkbox, switch or toggle cell in it: the shape of a hand-built rows-by-columns\n    // on/off grid (a permissions matrix, a \"what syncs\" grid). Anchored at the start of the file with lookaheads, so matching stays linear.\n    pattern: /^(?=[\\s\\S]*<table\\b)(?=[\\s\\S]*(?:role\\s*=\\s*[\"']checkbox[\"']|<Checkbox\\b|<Switch\\b|<Toggle\\b))/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"ToggleMatrix\"],\n    reason: \"a hand-built grid of on/off cells. ToggleMatrix is the one generic rows-by-columns matrix (RolePermissionMatrix is an adapter over it): rows with a label and a description, columns with a label, and a cell that is on, off or unavailable with a reason printed IN the cell (readable on a phone, no hover), a header checkbox that sets a whole column (checked, mixed, disabled), a read-only mode, a lock on a column that cannot be edited, a busy spinner per cell, group headings, and headers aligned over their cells down to 390px wide. A DataTable with a Checkbox in each cell is the same hand-built grid and loses the column control and the aligned headers. A table of records that merely has a selection checkbox is the case a UI-LIBRARY-ALLOW reason covers. DX-4963.\",\n  },\n  {\n    id: \"setting-row-long-value-inline\",\n    // A SettingRow whose own props hold a CopyValue as the control and no `layout` prop: the long value sits beside the text. The\n    // negative lookahead scans the same opening tag the match does, so the rule stays inside one tag.\n    pattern: new RegExp(\n      String.raw`<SettingRow\\b(?!${PROP_UNIT}*?\\slayout\\s*=)${PROP_UNIT}*?\\scontrol\\s*=\\s*\\{\\s*<CopyValue\\b`,\n    ),\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: ['SettingRow layout=\"stacked\"'],\n    reason: 'a copyable URL or token in a SettingRow control is laid out beside the label from 640px up, and a value box that cannot shrink takes the whole row: the label and description wrap one word per line, or the box runs past the card edge with its copy button out of view. SettingRow takes layout=\"stacked\": label and description on top, the control full width under them at every width, so CopyValue truncates inside its box with the copy button always visible. Use it for any control that holds a long value to read or copy. DX-4968.',\n  },\n  // ---- DX-5567: a keyword search box has its clear (x) inside it.\n  {\n    id: \"bare-search-input\",\n    pattern: new RegExp(tagWithAttr(\"Input\", \"type\", \"search\")),\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"SearchInput\"],\n    reason: 'an Input with type=\"search\" drawn as a keyword search box. SearchInput is the one search box: the search icon at its leading edge and, only while it holds text, a \"Clear search\" x button inside the field at its trailing edge that empties the value and returns focus to the box (the browsers own clear glyph is suppressed so only this one shows). Hosts pass `value` and `onValueChange(value)`; a list that applies on Enter or blur also commits when the value is emptied. A search that must not carry a clear button is the case a UI-LIBRARY-ALLOW reason covers. DX-5567.',\n  },\n  // ---- DX-4985: a stored secret is shown, never an input. Three shapes of the old way, one rule each.\n  {\n    id: \"bare-password-input-for-secret\",\n    pattern: new RegExp(tagWithAttr(\"Input\", \"type\", \"password\")),\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"SecretField\"],\n    reason: 'an Input with type=\"password\" over a credential. A SECRET THAT CAN BE STORED is never an input while it is stored: SecretField draws the masked value with its first and last characters, a status from a real test of the secret (verified, failed with the provider\\'s reason, unverifiable, not checked), a Re-verify button and Clear, and the input only when nothing is stored or after Clear. Replacing is Clear, then paste. A password the person is choosing or typing to sign in is PasswordInput; this rule is for a credential the app keeps. DX-4985.',\n  },\n  {\n    id: \"local-secret-row\",\n    // The old app wrapper by its name (declared or used), and any local Secret/Credential/Token/ApiKey Row/Field/Input component\n    // declared in app code: they exist to draw an input over a stored secret.\n    pattern: /<SecretRow\\b|\\b(?:function|const)\\s+(?:Secret|Credential|Token|ApiKey)\\w*(?:Row|Field|Input)\\b/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"SecretField\"],\n    reason: 'a local wrapper that draws a stored secret (a \"SecretRow\": a password box that says \"Saved and hidden. Paste a new value to replace it.\"). That is the shape the stored-secret rule retired: an input over a working credential invites pasting over it and says nothing about whether it works. SecretField is the one component: no input while stored, masked ends, status icon and words, Re-verify, Clear (staged inside a batch-save form with `clear=\"staged\"`, at once in a row with `clear=\"immediate\"`). Delete the wrapper and pass SecretField the server\\'s hint, status and updated-by. DX-4985.',\n  },\n  {\n    id: \"hand-built-masked-secret\",\n    // A string that is nothing but dots: the placeholder or display a stored secret is hidden behind.\n    pattern: /[\"'`]•{4,}[\"'`]/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"SecretField\"],\n    reason: 'a hand-made run of dots standing in for a stored secret (a placeholder over a password box, or a masked token drawn by hand). SecretField draws the stored face itself: the first and last characters from `hint` around a fixed mask, so no screen invents its own mask, its own badge or its own \"Check again\". DX-4985.',\n  },\n  {\n    id: \"secret-field-without-status\",\n    // A SecretField opening tag with no `status` prop, scanned inside the one tag. A secret the app keeps is tested, and \"not testable\"\n    // is still a status the caller words (`{ kind: \"unverifiable\", message }`).\n    pattern: new RegExp(String.raw`<SecretField\\b(?:(?!\\sstatus\\b)${PROP_UNIT})*\\/?>`),\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"SecretField status={...} onVerify={...}\"],\n    reason: 'a SecretField with no `status`. Without one the stored face reads \"Not checked\" for ever, which hides whether the credential works. Pass the server\\'s result of testing it (`verified`, `failed` with the provider\\'s reason, `checking`, `unchecked`) plus `onVerify` for the Re-verify button, or `{ kind: \"unverifiable\", message }` with the reason nothing can test it (an OAuth client secret). A SecretField that only ever shows a secret once, at creation (nothing stored), is the case a UI-LIBRARY-ALLOW reason covers. DX-4985.',\n  },\n  // ---- DXUI-28: a colour value is picked with ColorPicker.\n  {\n    id: \"native-colour-input\",\n    pattern: /\\stype\\s*=\\s*(?:\"color\"|'color'|\\{\\s*(?:\"color\"|'color')\\s*\\})/,\n    // I18N-ALLOW: component names a developer-facing lint hint points at, never user text\n    preferInstead: [\"ColorPicker\"],\n    reason: 'an input of type=\"color\". The browser draws its own picker, different on every platform and outside the theme. ColorPicker is the one colour control: a swatch button that opens a saturation/brightness area, a hue slider, a #rrggbb hex field that shows a bad value as a field error, and optional preset swatches; it works from the keyboard, and `onChange` fires with the committed colour on release rather than on every pointer move. Use it for any colour value. DXUI-28.',\n  },\n] as const;\n"],"names":["EXPR_STRING","braceGroup","depth","nested","PROP_UNIT","attr","name","value","tagWithAttr","tag","COMPONENT_GUIDANCE"],"mappings":"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"}

package/dist/lib/confidence.js

@@ -0,0 +1,22 @@
+function i(t, n) {
+  if (!Number.isFinite(t) || !Number.isFinite(n) || n <= 0 || t <= 0) return null;
+  const e = Math.round(Math.min(t, n) / n * 5);
+  return Math.max(1, Math.min(5, e));
+}
+const u = {
+  // I18N-ALLOW: English reference word for consumers outside React; components render the provider's `confidenceBar.levels`
+  1: "Just a guess",
+  // I18N-ALLOW: English reference word for consumers outside React; components render the provider's `confidenceBar.levels`
+  2: "Somewhat unsure",
+  // I18N-ALLOW: English reference word for consumers outside React; components render the provider's `confidenceBar.levels`
+  3: "Fairly confident",
+  // I18N-ALLOW: English reference word for consumers outside React; components render the provider's `confidenceBar.levels`
+  4: "Confident",
+  // I18N-ALLOW: English reference word for consumers outside React; components render the provider's `confidenceBar.levels`
+  5: "Highly confident"
+};
+export {
+  u as CONFIDENCE_LEVEL_LABELS,
+  i as confidenceLevel
+};
+//# sourceMappingURL=confidence.js.map

package/dist/lib/confidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.js","sources":["../../src/lib/confidence.ts"],"sourcesContent":["/* ----------------------------------------------------------------------------\n   THE FIVE-STEP CONFIDENCE SCALE, AS DATA — how a 1-5 rating READS.\n\n   React-free on purpose (it is exported from `@50arms/ui/pure`), because not\n   every surface that draws a rating is a React consumer of this library: the\n   demand letter's verification overlay is a Vue package, and it bundles these\n   from here rather than keeping its own copy of the rounding rule.\n   Its colours come the same way, from `dist/confidence.css`. One scale, one\n   source — a second copy is how a letter and the screen beside it came to\n   disagree about what a 4 is (SG-843 / SG-901).\n   -------------------------------------------------------------------------- */\n\n/** One of the five steps of the confidence scale — see `ConfidenceBar` for how each is drawn. */\nexport type ConfidenceLevel = 1 | 2 | 3 | 4 | 5;\n\n/**\n * A RATING to one of the five confidence steps, or null when there is no\n * rating on a real scale to draw.\n *\n * A five-point rating maps one-to-one. Any other scale is mapped by its\n * fraction, so a colour and a length keep one meaning whatever scale a consumer\n * rates on. A rating below one step is \"not rated\", never level 1: a zero is\n * the absence of a rating, and drawing it as the lowest earned level would\n * claim a judgement nobody made.\n *\n * The fraction feeds a COLOUR and a LENGTH, never a printed figure — a step is\n * a judgement five values wide and survives the trip; a percentage is a figure\n * and does not.\n */\nexport function confidenceLevel(rating: number, scale: number): ConfidenceLevel | null {\n  if (!Number.isFinite(rating) || !Number.isFinite(scale) || scale <= 0 || rating <= 0) return null;\n  const step = Math.round((Math.min(rating, scale) / scale) * 5);\n  return Math.max(1, Math.min(5, step)) as ConfidenceLevel;\n}\n\n/**\n * Each level's own word, the operator's scale (SG-843): 4 is \"Confident\" and 5\n * is \"Highly confident\", so the two readings of \"fine\" stay distinguishable in\n * words exactly as they are in colour and length.\n *\n * These are the ENGLISH words for a non-React consumer that cannot read the\n * provider (the demand letter's Vue overlay bundles them, SG-901). Components\n * read `confidenceBar.levels` from the provider, whose English set is this very\n * object, so there is one place the English lives.\n */\nexport const CONFIDENCE_LEVEL_LABELS: Readonly<Record<ConfidenceLevel, string>> = {\n  // I18N-ALLOW: English reference word for consumers outside React; components render the provider's `confidenceBar.levels`\n  1: \"Just a guess\",\n  // I18N-ALLOW: English reference word for consumers outside React; components render the provider's `confidenceBar.levels`\n  2: \"Somewhat unsure\",\n  // I18N-ALLOW: English reference word for consumers outside React; components render the provider's `confidenceBar.levels`\n  3: \"Fairly confident\",\n  // I18N-ALLOW: English reference word for consumers outside React; components render the provider's `confidenceBar.levels`\n  4: \"Confident\",\n  // I18N-ALLOW: English reference word for consumers outside React; components render the provider's `confidenceBar.levels`\n  5: \"Highly confident\",\n};\n"],"names":["confidenceLevel","rating","scale","step","CONFIDENCE_LEVEL_LABELS"],"mappings":"AA6BO,SAASA,EAAgBC,GAAgBC,GAAuC;AACrF,MAAI,CAAC,OAAO,SAASD,CAAM,KAAK,CAAC,OAAO,SAASC,CAAK,KAAKA,KAAS,KAAKD,KAAU,EAAG,QAAO;AAC7F,QAAME,IAAO,KAAK,MAAO,KAAK,IAAIF,GAAQC,CAAK,IAAIA,IAAS,CAAC;AAC7D,SAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAGC,CAAI,CAAC;AACtC;AAYO,MAAMC,IAAqE;AAAA;AAAA,EAEhF,GAAG;AAAA;AAAA,EAEH,GAAG;AAAA;AAAA,EAEH,GAAG;AAAA;AAAA,EAEH,GAAG;AAAA;AAAA,EAEH,GAAG;AACL;"}

package/dist/lib/date-timeline/scale.js

@@ -0,0 +1,197 @@
+import { DAY_MS as M } from "../../components/chart/time-series-scale.js";
+const l = 1, E = 120, p = 12, L = 60, O = 20, X = 5;
+function H(t) {
+  return t >= L ? "days" : t >= O ? "weeks" : t >= X ? "months" : "quarters";
+}
+function Y(t) {
+  if (!Number.isFinite(t) || t < l || t > E)
+    throw new Error(`timeline: pxPerDay must be a number from ${l} to ${E}`);
+}
+function A(t) {
+  return Math.min(E, Math.max(l, t));
+}
+function v(t, n) {
+  return A(t * n);
+}
+const k = 100, N = Math.log(E / l);
+function Z(t) {
+  return Math.log(t / l) / N * k;
+}
+function $(t) {
+  return A(l * Math.exp(t / k * N));
+}
+const U = 1, b = 2, I = 16, R = 400, C = 2e-3;
+function q(t, n) {
+  const e = n === U ? t * I : n === b ? t * R : t;
+  return Math.exp(-e * C);
+}
+const G = 1.25;
+function K(t, n, e, r, o) {
+  return Math.max(0, r + _(t, n, e) - o);
+}
+function B(t, n, e, r, o) {
+  return e + (n + t - o) / r;
+}
+function m(t) {
+  const n = t.getTime();
+  if (!Number.isFinite(n)) throw new Error("timeline: an invalid Date reached the date axis");
+  const e = Date.UTC(t.getFullYear(), t.getMonth(), t.getDate()) / M, r = ((t.getHours() * 60 + t.getMinutes()) * 60 + t.getSeconds()) * 1e3 + t.getMilliseconds();
+  return e + r / M;
+}
+function V(t) {
+  const n = new Date(Math.floor(t) * M);
+  return new Date(n.getUTCFullYear(), n.getUTCMonth(), n.getUTCDate());
+}
+function x(t) {
+  const n = new Date(Math.floor(t) * M);
+  return { year: n.getUTCFullYear(), month: n.getUTCMonth(), weekday: n.getUTCDay() };
+}
+const g = (t, n) => Date.UTC(t, n, 1) / M;
+function w(t, n, e) {
+  const { year: r, month: o, weekday: i } = x(t);
+  return n === "days" ? Math.floor(t) : n === "weeks" ? Math.floor(t) - (i - e + 7) % 7 : n === "months" ? g(r, o) : g(r, o - o % 3);
+}
+function T(t, n) {
+  if (n === "days") return t + 1;
+  if (n === "weeks") return t + 7;
+  const { year: e, month: r } = x(t);
+  return g(e, r + (n === "months" ? 1 : 3));
+}
+function j(t) {
+  return Math.floor(x(t).month / 3) + 1;
+}
+function z(t) {
+  return x(t).year;
+}
+function F(t, n) {
+  if (n < t) throw new Error("timeline: an item ends before it starts");
+}
+const S = { days: 14, weeks: 2, months: 1, quarters: 1 };
+function J(t, n, e, r, o = []) {
+  const i = m(n);
+  let u = i, a = i;
+  for (const c of o) {
+    const f = m(c);
+    u = Math.min(u, f), a = Math.max(a, f);
+  }
+  for (const c of t) {
+    const f = m(c.start), d = m(c.end);
+    if (F(f, d), u = Math.min(u, f), a = Math.max(a, d), c.plannedEnd) {
+      const D = m(c.plannedEnd);
+      u = Math.min(u, D), a = Math.max(a, D);
+    }
+  }
+  let s = w(u, e, r), h = T(w(a, e, r), e);
+  for (let c = 0; c < S[e]; c++)
+    s = w(s - 1, e, r), h = T(h, e);
+  return { startDay: s, endDay: h };
+}
+function _(t, n, e) {
+  return (t - n) * e;
+}
+function Q(t, n) {
+  return _(t.endDay, t.startDay, n);
+}
+function tt(t, n, e) {
+  const r = [];
+  for (let o = t.startDay; o < t.endDay; ) {
+    const i = T(o, n);
+    r.push({ startDay: o, endDay: i, x: _(o, t.startDay, e), width: (i - o) * e }), o = i;
+  }
+  return r;
+}
+function P(t, n, e) {
+  return _(m(t), n, e);
+}
+function nt(t, n, e) {
+  F(m(t.start), m(t.end));
+  const r = P(t.start, n.startDay, e);
+  return { left: r, width: P(t.end, n.startDay, e) - r };
+}
+function y(t, n) {
+  return new Date(t.getFullYear(), t.getMonth(), t.getDate() + n, t.getHours(), t.getMinutes(), t.getSeconds(), t.getMilliseconds());
+}
+function et(t, n, e) {
+  if (!Number.isInteger(e)) throw new Error("timeline: an edit is a whole number of days");
+  const r = m(t.end) - m(t.start);
+  return n === "move" ? { start: y(t.start, e), end: y(t.end, e) } : n === "end" ? { start: t.start, end: y(t.end, Math.max(e, Math.ceil(-r))) } : { start: y(t.start, Math.min(e, Math.floor(r))), end: t.end };
+}
+function rt(t, n, e) {
+  const r = m(t);
+  return Math.min(Math.max(n, e.startDay - r), e.endDay - 1 - r);
+}
+function ot(t, n, e) {
+  return Math.max(0, t - (n - e) / 2);
+}
+function at(t) {
+  if (Number.isNaN(t)) throw new Error("timeline: progress is not a number");
+  return Math.min(1, Math.max(0, t));
+}
+function it(t) {
+  const n = /* @__PURE__ */ new Set();
+  for (const e of t) {
+    if (Number.isNaN(e.date.getTime())) throw new Error(`timeline: marker "${e.id}" has an invalid date`);
+    if (n.has(e.id)) throw new Error(`timeline: two markers share the id "${e.id}"`);
+    n.add(e.id);
+  }
+}
+function st(t, n, e) {
+  const r = [];
+  return t.map((o, i) => ({ ...o, index: i })).sort((o, i) => o.x - i.x || o.index - i.index).map(({ x: o, width: i, index: u }) => {
+    const a = Math.min(Math.max(o - i / 2, 0), Math.max(n - i, 0));
+    let s = r.findIndex((h) => h + e <= a);
+    return s < 0 && (s = r.length), r[s] = a + i, { index: u, left: a, row: s };
+  });
+}
+function ct(t, n) {
+  return -(t + 1) * n;
+}
+function ut(t, n, e, r) {
+  const o = Array.from({ length: n }, () => -1 / 0), i = Array.from({ length: n }), u = [];
+  return t.map((a, s) => ({ ...a, index: s })).sort((a, s) => a.x - s.x || a.index - s.index).forEach(({ x: a, width: s, index: h }) => {
+    let c = o.findIndex((D) => D + e <= a);
+    c === -1 && (c = o.indexOf(Math.min(...o)));
+    const f = i[c];
+    f && f.x + f.maxWidth + e > a && (f.maxWidth = Math.max(r, a - f.x - e));
+    const d = { x: a, maxWidth: s, index: h, lane: c };
+    u.push(d), i[c] = d, o[c] = a + s;
+  }), u.sort((a, s) => a.index - s.index).map(({ index: a, lane: s, maxWidth: h }) => ({ index: a, lane: s, maxWidth: h }));
+}
+export {
+  p as DEFAULT_PX_PER_DAY,
+  G as KEY_ZOOM_FACTOR,
+  E as MAX_PX_PER_DAY,
+  l as MIN_PX_PER_DAY,
+  k as ZOOM_SLIDER_MAX,
+  y as addDays,
+  it as assertMarkers,
+  Y as assertPxPerDay,
+  nt as barBox,
+  rt as clampMarkerDays,
+  at as clampProgress,
+  A as clampPxPerDay,
+  B as dayAtViewportX,
+  _ as dayToX,
+  et as editSpan,
+  V as fromDayNumber,
+  P as instantToX,
+  ut as layoutMarkerFlags,
+  st as layoutMarkerTags,
+  ct as markerTagTop,
+  T as nextUnitStart,
+  Z as pxPerDayToSlider,
+  j as quarterOf,
+  v as scalePxPerDay,
+  K as scrollLeftForAnchor,
+  ot as scrollLeftToCenter,
+  $ as sliderToPxPerDay,
+  H as tickUnitFor,
+  J as timelineRange,
+  m as toDayNumber,
+  Q as trackWidth,
+  w as unitStart,
+  tt as unitTicks,
+  q as wheelZoomFactor,
+  z as yearOf
+};
+//# sourceMappingURL=scale.js.map