@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScCalendar.md

@@ -0,0 +1,268 @@
+---
+component: ScCalendar
+package: "@streamoid/ui"
+category: forms
+status: legacy
+renders: div
+tags: [calendar, date, datepicker, month, day, range, date-range]
+related: [ScCalendarDateComps, ScHDivider, ScModal]
+do_not_confuse_with: [ScCalendarDateComps, ScCounter, ScPagination]
+---
+
+# ScCalendar
+
+**A single-month day grid — and an unfinished one.** 20rem card with
+"`{Month} {Year}` ‹ ›" in the header, a divider, then 28–42 `ScCalendarDateComps`
+cells (whole weeks: `ceil((firstWeekday + daysInMonth) / 7) * 7`). **Its own grid CSS pins every cell to row 1 / column 1, so all the dates
+render stacked on top of each other.** It has no host consumer, and the date-range
+picker that actually shipped (`ExportDateModal` in `@streamoid/settings`) hand-rolls
+this same chrome instead of using it.
+
+> **status: legacy.** Do not reach for this in new work until Gotcha 1 is fixed in
+> the DS. If you need a date picker today, copy the pattern from
+> `packages/settings/src/export-date-modal.tsx`, or use `ScCalendarDateComps`
+> directly with your own grid.
+
+## TL;DR for agents
+
+- **Reach for it when:** you're fixing or finishing this component. Otherwise, don't.
+- **Don't reach for it when:** you need a working date or date-range picker →
+  `ExportDateModal` from `@streamoid/settings` (a modal with prev/next-month fill,
+  real range selection and future-date blocking), or build your own grid out of
+  `ScCalendarDateComps`.
+- **Five things that will bite you:**
+  1. **All cells collapse into one grid cell.** Every child gets
+     `grid-column: 1 / span 1 !important; grid-row: 1 / span 1 !important`.
+  2. **There is no weekday header row.** No S M T W T F S — day 1 lands under
+     nothing.
+  3. **`month`/`year` are controlled-only.** `onMonthChange` just notifies; if you
+     don't store it, the arrows are dead.
+  4. **No range support in practice.** It only ever emits
+     `empty` / `today` / `range-start` / `default`, so `range` and `range-end`
+     never appear no matter what you pass.
+  5. **`today` beats `selectedDate`.** Selecting today shows the today underline,
+     not the selected fill.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScCalendar } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+It must be driven from state or the arrows do nothing:
+
+```tsx
+const [view, setView] = useState({ m: new Date().getMonth(), y: new Date().getFullYear() });
+const [picked, setPicked] = useState<Date | undefined>();
+
+<ScCalendar
+  month={view.m}
+  year={view.y}
+  selectedDate={picked}
+  onMonthChange={(m, y) => setView({ m, y })}
+  onDateSelect={setPicked}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `month` | `number` | current month | **0-indexed** (0 = January). Passing `1` renders February. Falls back to `new Date().getMonth()` when `undefined`. |
+| `year` | `number` | current year | Full year, e.g. `2026`. Falls back to `new Date().getFullYear()`. |
+| `selectedDate` | `Date` | – | A single date. Rendered as `range-start` (left-rounded fill) — **not** as a range, and **not** when it is today. Ignored when it falls outside `month`/`year`. |
+| `onDateSelect` | `(date: Date) => void` | – | Fires with a real `Date` for in-month cells only. Empty cells get no handler and no pointer cursor. |
+| `onMonthChange` | `(month: number, year: number) => void` | – | Fires from the ‹ › icons with the **next** month/year, already wrapped across the year boundary. Does not change what the component renders. |
+| `className` | `string` | – | Concatenated after the root class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root `div`. |
+
+No `minDate`, no `maxDate`, no `disabledDates`, no `rangeStart`/`rangeEnd`, no
+`weekStartsOn`, no locale, no `size`.
+
+### The cell states it can actually produce
+
+| Condition | State passed to `ScCalendarDateComps` |
+|---|---|
+| index before the 1st, or after the last day | `"empty"` (blank text) |
+| the cell is today, in the displayed month | `"today"` (1px bottom border) |
+| the cell equals `selectedDate`, and isn't today | `"range-start"` (overlay fill, left-rounded) |
+| everything else | `"default"` |
+
+`"range"`, `"range-end"` and `"hover"` are declared on `ScCalendarDateComps` but
+`ScCalendar` never emits them.
+
+### Recipes
+
+```tsx
+// Inside a popover/modal, wired as a single-date picker
+<ScModal /* … */>
+  <ScCalendar
+    month={view.m}
+    year={view.y}
+    selectedDate={value}
+    onMonthChange={(m, y) => setView({ m, y })}
+    onDateSelect={(d) => { setValue(d); close(); }}
+  />
+</ScModal>
+
+// Blocking future dates — the component can't; filter in your handler
+<ScCalendar
+  month={view.m}
+  year={view.y}
+  onMonthChange={(m, y) => setView({ m, y })}
+  onDateSelect={(d) => { if (d <= new Date()) setValue(d); }}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere, currently. The surfaces it was drawn for are:
+
+- **A date-range export modal** in billing / usage history — that surface exists and
+  is served by `ExportDateModal` (`@streamoid/settings`, rendered from
+  `billing-content.tsx:2123`), which reimplements this card's exact chrome
+  (same `MONTH_NAMES`, same 72px arrow row, same `surface-canvasbase` /
+  `radius-3xl` / `spacing-6xl` shell) with the features `ScCalendar` lacks.
+- **A `ScTextField`-adjacent date popover.** Note there is **no** `ScDateField` in
+  this library — nothing wraps a calendar in a field, so the trigger, the popover
+  and the formatting are all yours.
+
+It composes `ScHDivider` and `ScCalendarDateComps` internally.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are repairing the DS. Otherwise: not yet.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A working **date-range** picker in a modal (billing export, usage history) | `ExportDateModal` from `@streamoid/settings` |
+| A custom grid where you need real range/hover states, or 6-row months, or a weekday header | `ScCalendarDateComps` + your own CSS grid |
+| A text input the user types a date into | `ScTextField` (there is no `ScDateField`) |
+| Stepping a number up/down | `ScCounter` |
+| Paging through a list | `ScPagination` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCalendarDateComps` — one day cell; the only part of this pair that behaves | `ScCalendar` is the (broken) grid around it |
+| `ExportDateModal` (`@streamoid/settings`) — the shipped range picker | Different package, not a `@streamoid/ui` export |
+| `ScCounter` / `ScPagination` — also have ‹ › arrow pairs | Nothing to do with dates |
+
+---
+
+## 4. Why to use it
+
+Honestly: for the maths, once the CSS is fixed. What it gets right today —
+
+- **Correct month arithmetic.** Leading-blank count from `getDay()`, day count from
+  the `new Date(y, m + 1, 0)` trick, total cells rounded up to whole weeks, and
+  year-boundary wrapping in both arrows. That's the part people get wrong.
+- **Real `Date` objects out.** `onDateSelect` hands you a constructed
+  `new Date(year, month, day)`, not a string you have to parse.
+- **Tokenised shell** — `surface-canvasbase`, `radius-3xl`, `spacing-6xl`, and a
+  `ScHDivider`, so the card matches every other panel in both themes.
+
+What you'd have to add to ship it: the grid fix, a weekday header, a 6th row, real
+range state, min/max dates, and keyboard support.
+
+---
+
+## Gotchas
+
+**1. Every date renders in the same grid cell.** `ScCalendar.module.css` defines 35
+positioning classes (`.scCalendarDateCompsInstance` … `Instance35`), but the render
+loop passes **only the first one** to every child:
+
+```tsx
+// ScCalendar.tsx:154 — the same class on all 28–42 cells
+<ScCalendarDateComps key={i} date={dayNumber || ""} state={state}
+  className={styles.scCalendarDateCompsInstance} … />
+```
+
+and that class is `grid-column: 1 / span 1 !important; grid-row: 1 / span 1 !important`.
+Result: the whole month stacks in the top-left square. The fix is to drop the
+per-instance classes and let the grid auto-place (`.calendarGrid` is already
+`grid-template-columns: repeat(7, minmax(0,1fr))`) — but that is a DS change, not
+something a call site can work around, because the rules are `!important`.
+
+**2. No weekday header.** The grid starts at the first date cell. Columns are Sunday
+-first (`getDay()` where 0 = Sunday) and there is no `weekStartsOn` prop, so a
+Monday-first locale needs a different component.
+
+**3. `grid-template-rows: repeat(5, …)` only declares 5 rows,** but a 31-day month
+starting on a Saturday needs 6. Those cells fall into an implicit auto row.
+
+**4. It is controlled-only.**
+
+```tsx
+// WRONG — arrows fire onMonthChange but the calendar never moves
+<ScCalendar onMonthChange={(m, y) => console.log(m, y)} />
+
+// RIGHT — you own the view
+<ScCalendar month={view.m} year={view.y} onMonthChange={(m, y) => setView({ m, y })} />
+```
+
+**5. `month` is 0-indexed.** `month={1}` is February. `month={12}` is not December —
+`MONTH_NAMES[12]` is `undefined` and the header renders "undefined 2026" while
+`new Date(y, 12, 1)` silently rolls into next January.
+
+**6. `today` outranks `selectedDate`.** The today check runs first and returns early,
+so selecting today shows the underline, never the fill. Two different dates can
+never both be highlighted.
+
+**7. `selectedDate` gives you a left-rounded "range-start" pill, not a symmetric
+selection.** It looks like the start of a range that isn't there.
+
+**8. The ‹ › arrows are raw SVGs with `onClick`.** No `<button>`, no `tabIndex`, no
+`aria-label`, and no way to disable the next arrow at the current month (compare
+`ExportDateModal`, which greys it out). Cells are `div`s too — the whole calendar is
+mouse-only and unreachable by keyboard.
+
+**9. Nothing can be disabled.** No `minDate`/`maxDate`/`disabledDates`. Every
+in-month cell is clickable; filter inside `onDateSelect`.
+
+**10. `className` is concatenated unguarded,** so omitting it puts the literal
+`undefined` in the root class list. Don't assert on exact class strings.
+
+**11. Fixed `width: 20rem`.** Not responsive, no `size` prop; override via
+`className` if you must.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Neither is true here, so to be precise: **no consumer anywhere.** No host dashboard
+renders it, and it is not an agent-runtime component. Its only render is the DS
+gallery, which resolves it through a name→component map
+(`apps/docs/utils/componentMap.tsx:10`, with its prop metadata at
+`apps/docs/utils/componentData.ts:307`). The surface it belongs to —
+the billing/usage **date-range export modal** — is served by a hand-rolled clone at
+`packages/settings/src/export-date-modal.tsx`, which is the strongest available
+signal that this component was never usable as shipped.
+
+---
+
+## Related
+
+- `ScCalendarDateComps` — the single day cell; the usable half of this pair.
+- `ExportDateModal` (`@streamoid/settings`) — the date-range picker that actually ships.
+- `ScHDivider` — the header rule it composes.
+- `ScModal` / `ScPopUpMenu` — what you'd put a calendar inside; neither knows about dates.

package/dist/docs/ScCalendarDateComps.md

@@ -0,0 +1,264 @@
+---
+component: ScCalendarDateComps
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div
+tags: [calendar, date, day, cell, date-cell, range, today]
+related: [ScCalendar, ScTaxonomyPill, ScBadges]
+do_not_confuse_with: [ScCalendar, ScBadges, ScCounter]
+---
+
+# ScCalendarDateComps
+
+**One day cell in a calendar grid.** A 2.5rem-wide box with a centred day number and
+seven skins: plain, hovered, today (thin bottom rule), range-start (left-rounded
+fill), range-end (right-rounded fill), mid-range (flat fill), and empty. It is a
+pure leaf — no date logic, no `Date`, just a string and a state.
+
+The awkward plural in the name is a Figma export artefact; it renders exactly **one**
+cell.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building your own calendar grid and want the DS's
+  day-cell skins — including the half-rounded range ends.
+- **Don't reach for it when:** you want a whole month laid out for you. `ScCalendar`
+  is the wrapper, but its grid CSS is broken (see its README), so building the grid
+  yourself is currently the *recommended* path.
+- **Four things that will bite you:**
+  1. `date` defaults to **`"31"`**. ⚠️ Forget it and every cell says 31.
+  2. `state="empty"` **does not blank the number** — it only un-tokenises the text
+     colour. Pass `date=""` as well.
+  3. **`:hover` fires on every cell, empty ones included.** There's no `disabled`.
+  4. It's a bare `div`. No `role`, no `tabIndex`, no keyboard. `onClick` works only
+     because DOM props are spread.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScCalendarDateComps } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScCalendarDateComps date="14" state="today" />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `date` | `string` | `"31"` | ⚠️ Has a real default. A **string**, not a number — `String(day)`. Rendered with a trailing space in the text node. |
+| `state` | `"default"` \| `"hover"` \| `"today"` \| `"range-start"` \| `"range-end"` \| `"range"` \| `"empty"` | `"default"` | Skin only. See the table below. |
+| `className` | `string` | – | Concatenated between the root class and the state class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root `div` — `onClick`, `style`, `role`, `tabIndex`, `aria-*`, `data-*`. This is how you make it interactive. |
+
+### What each state paints
+
+| `state` | Visual | Note |
+|---|---|---|
+| `default` | day number in `text-and-icons-primary`, no fill | **No CSS class is emitted for this state** — there is no `.state-default` rule, so you can't target it |
+| `hover` | `fill-neutral-neutralplus` background | Force-renders the hover skin (Figma parity/screenshots) — real `:hover` already does this |
+| `today` | 1px bottom border in `text-and-icons-tertiary` | Underline only, no fill |
+| `range-start` | `surface-overlay` fill, radius on the **left** corners only | Designed to butt up against the next cell |
+| `range-end` | `surface-overlay` fill, radius on the **right** corners only | |
+| `range` | `fill-neutral-neutraltohover` fill, square corners | The days between |
+| `empty` | `.date { color: unset }` — the number inherits whatever colour the ancestor has | Does **not** hide or dim the number |
+
+### Recipes
+
+```tsx
+// Your own month grid — 7 columns, no gap, so range fills join up
+<div style={{ display: "grid", gridTemplateColumns: "repeat(7, minmax(0,1fr))", gap: 0 }}>
+  {["S","M","T","W","T","F","S"].map((d, i) => (
+    <div key={i} style={{ textAlign: "center", fontSize: 12,
+      color: "var(--alias-text-and-icons-tertiary)" }}>{d}</div>
+  ))}
+  {cells.map((c) => (
+    <ScCalendarDateComps
+      key={c.key}
+      date={c.inMonth ? String(c.day) : ""}
+      state={stateFor(c)}
+      onClick={c.inMonth ? () => pick(c.date) : undefined}
+      style={{ cursor: c.inMonth ? "pointer" : "default", width: "unset" }}
+    />
+  ))}
+</div>
+
+// A real range: start / middles / end
+const stateFor = (c) => {
+  if (!c.inMonth) return "empty";
+  if (same(c.date, start)) return "range-start";
+  if (same(c.date, end)) return "range-end";
+  if (start && end && c.date > start && c.date < end) return "range";
+  if (isToday(c.date)) return "today";
+  return "default";
+};
+
+// Make it accessible — the component won't do it for you
+<ScCalendarDateComps
+  date="14"
+  state="range-start"
+  role="button"
+  tabIndex={0}
+  aria-label="14 March 2026"
+  aria-pressed
+  onClick={pick}
+  onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") pick(); }}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Inside a calendar grid you control** — 7 columns, `gap: 0`, `width: unset` on the
+  cell so it stretches to the column.
+- It is what `ScCalendar` renders internally (28–42 of them — whole weeks only).
+  `ScCalendar` also passes `onClick`/`style` through this component's DOM spread,
+  which is the only reason its cells are clickable at all.
+
+No host dashboard renders it directly.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are assembling a month grid and want the DS day-cell tokens (fills, the today
+  rule, the half-rounded range caps) rather than inventing them.
+- You need states `ScCalendar` can't produce — a genuine `range` / `range-end`, or a
+  forced `hover` for a screenshot.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A ready-made month with month arithmetic and ‹ › navigation | `ScCalendar` — but read its Gotcha 1 first; its grid CSS stacks all cells |
+| A working date-**range** picker, today | `ExportDateModal` from `@streamoid/settings` |
+| A small non-date chip / count | `ScBadges` |
+| A tree node chip with expand/collapse | `ScTaxonomyPill` |
+| Numeric stepping | `ScCounter` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScCalendar` — the month card (header, divider, grid) | `ScCalendarDateComps` is one square inside it |
+| `ScBadges` — status/count chip | Similar footprint, different vocabulary and tokens |
+| The `range`/`range-end` states as produced by `ScCalendar` | `ScCalendar` never emits them; only you can |
+
+Naming: it's `ScCalendarDateComps` — plural "Comps", singular cell, and it lives in
+the folder `SC-Calendar date comps` (spaces in the path).
+
+---
+
+## 4. Why to use it
+
+- **The range caps are the hard part and they're already right.** `range-start` is
+  rounded left-only, `range-end` right-only, `range` square — so a selected span
+  reads as one continuous pill *provided your grid has `gap: 0`*. Getting that with
+  hand-rolled CSS usually produces gaps or double-rounded ends.
+- **Token-correct in both themes.** `surface-overlay` for the range caps,
+  `fill-neutral-neutraltohover` for the middle, `text-and-icons-tertiary` for the
+  today rule — no hardcoded greys to fix in light mode.
+- **Fully transparent.** It spreads every DOM prop, so you keep complete control of
+  semantics, keyboard handling and layout while inheriting only the skin.
+- **One place to restyle.** Change the day-cell look once and every calendar in the
+  product follows.
+
+---
+
+## Gotchas
+
+**1. `date` defaults to `"31"`.**
+
+```tsx
+// WRONG — a grid full of 31s
+{cells.map((c) => <ScCalendarDateComps key={c.key} state="default" />)}
+
+// RIGHT
+{cells.map((c) => <ScCalendarDateComps key={c.key} date={String(c.day)} />)}
+```
+
+**2. `state="empty"` still shows the number.** All the `empty` rule does is
+`.date { color: unset }`, which makes the text *inherit* the ancestor colour instead
+of the primary token — it does not hide, dim or disable anything. Blank the text
+yourself:
+
+```tsx
+// WRONG — the padding-day number is still visible, just in the wrong colour
+<ScCalendarDateComps date="29" state="empty" />
+
+// RIGHT
+<ScCalendarDateComps date="" state="empty" />
+```
+
+**3. Hover paints on empty cells too.** `.scCalendarDateComps:hover` is unqualified,
+so blank padding cells highlight under the cursor. Suppress it with your own rule if
+that matters — there is no `disabled` state.
+
+**4. No interactivity of its own.** Root is a plain `div`: no `role`, no `tabIndex`,
+no `onKeyDown`, no `aria-selected`. Everything you'd need for an accessible date grid
+you pass in yourself through the spread.
+
+**5. `state="default"` emits `undefined` into the class list.** `styles["state-default"]`
+doesn't exist (there is no `.state-default` rule), and `className` is concatenated
+unguarded, so a bare cell renders
+`class="…scCalendarDateComps undefined undefined"`. Cosmetic — but never assert on
+exact class strings, and don't try to style default cells via a state class.
+
+**6. Fixed `width: 2.5rem`.** In a `1fr` grid column you almost always want
+`width: unset` (which is exactly what `ScCalendar`'s per-cell classes force). Pass it
+via `style` or `className`.
+
+**7. `date` is a string, so you own formatting.** `date={5}` is a type error;
+`String(day)` — and note the component renders `{date} ` with a trailing space, so
+`textContent` in tests is `"5 "`, not `"5"`.
+
+**8. `state="hover"` is for design parity, not interaction.** Never wire it to your
+own mouse handlers; `:hover` already works.
+
+**9. Range fills break if your grid has a gap.** The half-rounded caps assume
+adjacent cells touch. `ScCalendar`'s own grid uses `gap: 0rem` for this reason.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Composed internally: `ScCalendar.tsx:150` renders one per grid cell —
+
+```tsx
+// npm-components  packages/ui/src/SC-Calendar/ScCalendar.tsx:150
+<ScCalendarDateComps
+  key={i}
+  date={dayNumber || ""}
+  state={state}
+  className={styles.scCalendarDateCompsInstance}
+  onClick={cellDate && state !== "empty" ? () => onDateSelect?.(cellDate) : undefined}
+  style={cellDate && state !== "empty" ? { cursor: "pointer" } : undefined}
+/>
+```
+
+If it gets a direct consumer it will most likely be a **billing/usage date-range
+export** popover — the surface currently served by the hand-rolled grid in
+`packages/settings/src/export-date-modal.tsx`, which would be the obvious first
+place to swap this cell in.
+
+---
+
+## Related
+
+- `ScCalendar` — the month wrapper; read its Gotcha 1 before using it.
+- `ExportDateModal` (`@streamoid/settings`) — the date-range picker that ships today.
+- `ScBadges` / `ScTaxonomyPill` — other small chips, unrelated vocabulary.