snice 7.8.0 → 7.9.0

package/docs/ai/components/calendar.md

@@ -5,18 +5,18 @@ Calendar with date selection and event support.
 ## Properties
 
 ```typescript
-value: Date | string = new Date();
+value: Date | string | null = null;    // null = nothing selected (initial state); today is marked by highlightToday, not by a selection
 view: 'month'|'week'|'day' = 'month';
 events: CalendarEvent[] = [];
 minDate: Date | string = '';           // attribute: min-date
 maxDate: Date | string = '';           // attribute: max-date
 disabledDates: (Date | string)[] = []; // JS-only; no attribute
 highlightToday: boolean = true;        // attribute: highlight-today
-showWeekNumbers: boolean = false;      // attribute: show-week-numbers
+showWeekNumbers: boolean = false;      // attribute: show-week-numbers — adds a leading week-number column (ISO-8601 when firstDayOfWeek=1, otherwise the week containing Jan 1 is week 1)
 firstDayOfWeek: number = 0;            // attribute: first-day-of-week (0=Sun, 1=Mon)
 locale: string = 'en-US';
 noDaySelect: boolean = false;          // attribute: no-day-select — display-only: day clicks don't select/highlight or fire calendar-change; event bars stay interactive
-cellSizing: 'square'|'stretch' = 'square'; // attribute: cell-sizing — square: cells as tall as the column is wide; stretch: rows collapse to content + event-lane reservation
+cellSizing: 'square'|'stretch' = 'square'; // attribute: cell-sizing — square: cells as tall as the column is wide; stretch: rows collapse to content (every event lane shown). Sizes the cell, and the cell's height sets the visible event-lane count
 ```
 
 ## Methods
@@ -33,7 +33,11 @@ cellSizing: 'square'|'stretch' = 'square'; // attribute: cell-sizing — square:
 
 - `calendar-change` -> `{ value: Date, calendar: SniceCalendarElement }`
 - `calendar-event-click` -> `{ event: CalendarEvent, calendar: SniceCalendarElement }`
-- `calendar-more-click` -> `{ date: Date, count: number, calendar: SniceCalendarElement }` — "+N more" chip clicked; does NOT fire `calendar-change`
+- `calendar-more-click` -> `{ date: Date, count: number, calendar: SniceCalendarElement }` — "+N more" chip clicked; does NOT fire `calendar-change`. **Cancelable**: `preventDefault()` suppresses the built-in day panel (see "+N more" default action)
+
+## Methods (overlay)
+
+- `closeEventPopover(options?: { returnFocus?: boolean })` - Closes the shared overlay (event popover or "+N more" day panel)
 
 ## CSS Parts
 
@@ -41,6 +45,8 @@ cellSizing: 'square'|'stretch' = 'square'; // attribute: cell-sizing — square:
 - `header` - Header with title and navigation buttons
 - `grid` - Day cells grid
 - `more-chip` - Per-day "+N more" overflow chip
+- `more-list` / `more-item` / `more-dot` / `more-panel-date` - Built-in "+N more" day panel internals
+- `week-number` / `week-number-header` - Week-number column cells (`show-week-numbers`)
 - `event-bar` / `event-avatar` / `event-tooltip` / `event-popover` - Event bar internals
 
 ## Basic Usage
@@ -58,21 +64,31 @@ calendar.events = [
 ];
 // Ranged events render as continuous stripes: one bar per week row, chopped
 // at week boundaries (squared corners on the continuing side, title repeats).
-// Concurrent events stack into lanes (start asc, longer first on ties);
-// max 3 lanes, deeper stacks collapse to a per-day "+N more" chip.
+// Concurrent events stack into lanes (start asc, longer first on ties).
+// Visible lanes are DERIVED PER WEEK from the day cell's height (see
+// "Event-lane budget"); deeper stacks collapse to a per-day "+N more" chip.
 // Chip: part="more-chip", role="button" tabindex=0 (Enter/Space), click ->
 // calendar-more-click { date, count }; the click never falls through to day
-// selection. Use it to open your own day/agenda view:
-//   calendar.addEventListener('calendar-more-click',
-//     (e) => showDay(e.detail.date, e.detail.count));
+// selection. Built-in default action, no wiring required — see
+// '"+N more" default action' below. Replace it with your own day/agenda view:
+//   calendar.addEventListener('calendar-more-click', (e) => {
+//     e.preventDefault();                       // cancels the built-in panel
+//     showDay(e.detail.date, e.detail.count);
+//   });
 // Bars: part="event-bar", click -> calendar-event-click.
 // Styling: color -> background; avatar?: string | {src?,name?,alt?} ->
 // <snice-avatar> on each bar (part="event-avatar"; name -> initials fallback);
+//   Adornment, not payload: a bar segment narrower than 4.5rem renders the
+//   title alone (class calendar__event-bar--compact, tighter padding) — the
+//   avatar would leave ~3 characters in a default-width month cell. Measured
+//   per segment, so a multi-day span keeps it; re-decided on resize.
 // className?: string -> added to bar classes AND part list, so
 // ::part(<className>) themes specific events from outside.
 // Tooltips: event.tooltip?: string (static), or on the element:
 //   eventTooltip: (event) => string | Node | Promise<string | Node>  // lazy/rich; wins over event.tooltip
-// Stale async results discarded on pointer-leave. Overlay part="event-tooltip".
+// Stale async results discarded on pointer-leave. Overlay part="event-tooltip";
+//   surface = --snice-tooltip-bg / --snice-tooltip-color (same pair as
+//   <snice-tooltip>), so it stays legible in both themes.
 // Popovers (click-to-open, interactive; STRICT per-event opt-in):
 //   event.popover?: boolean | string | Node | (() => Node)
 //   Resolution: inline content -> element eventPopover(event) => string|Node|Promise
@@ -81,12 +97,99 @@ calendar.events = [
 //   to bar; loading state while pending; stale results discarded.
 //   Bars with popover: role="button" tabindex=0, Enter/Space opens.
 //   calendar-event-click still fires. closeEventPopover() closes programmatically.
+// Overlay placement (both tooltip and popover): position: absolute inside
+//   ::part(base), NOT viewport-fixed — :host has `contain: layout style`, which
+//   makes the host the containing block for fixed descendants. Anchored to the
+//   bar (popover below / tooltip above), flipped at the viewport edge, clamped
+//   horizontally. Containment also makes the host a stacking context, so while
+//   an overlay shows the host carries a read-only `overlay-open` attribute and
+//   z-index: var(--snice-z-floating, 1000); restyle via
+//   snice-calendar[overlay-open] { z-index: ... }.
 
 calendar.addEventListener('calendar-change', (e) => {
   console.log('Selected:', e.detail.value);
 });
 ```
 
+## "+N more" Default Action
+
+Clicking (or Enter/Space on) the chip opens the shared overlay listing that
+day's hidden events — no listener required.
+
+- Panel = the same `.calendar__popover` element the event popover uses:
+  `role="dialog"`, `part="event-popover"`, Escape / outside-press dismiss,
+  focus moves into the panel and returns to the chip on close.
+- `aria-label` names the day; `part="more-panel-date"` heading + `part="more-list"`
+  (`role="list"`) of `<button part="more-item">` entries, each a
+  `part="more-dot"` colour dot (`event.color`) plus the title.
+- Entry click -> `calendar-event-click`; if the event has `popover` content the
+  same overlay drills into it, otherwise the panel closes.
+- Suppress with `preventDefault()` on `calendar-more-click`:
+
+```typescript
+calendar.addEventListener('calendar-more-click', (e) => {
+  e.preventDefault();      // built-in panel does not open
+  openMyDayView(e.detail.date);
+});
+```
+
+## Event-Lane Budget
+
+Visible lanes per week = how many fit the day cell's height. No flat cap.
+
+```
+lanes = max(1, floor((cellHeight - 2.125rem - chip) / 1.375rem))
+chip  = 1rem when the stack overflows (the "+N more" strip), else 0
+```
+
+Cell height comes from whatever sizes the cell:
+- `cell-sizing="square"` (default): `100cqw / 7` — the column width; wider calendar -> taller cells -> more lanes. Capped by the built-in `max-width: 37.5rem` (~5.4rem cell -> 2 lanes, 1 with the chip); lift with `::part(base) { max-width: none }`. Narrow calendars show fewer lanes than the flat 3-lane cap this replaced.
+- Definite host height: `snice-calendar { height: 40rem }` (or a sized flex/grid parent) — the six week rows share the room under the header, so the budget grows with it.
+- `cell-sizing="stretch"` with no imposed height: no budget — rows collapse to content and every lane is shown, no chip.
+
+Notes:
+- Re-derived on resize (`@observe('resize')`) — no need to re-assign `events`.
+- Row reservation is a floor, applied only when the cell is shorter than the stack it shows: 3.5rem for one lane, 4.5rem for one lane + chip. Above that all rows stay equal; below it (square cells under ~4.5rem, i.e. calendars under ~500px wide) the busy row still grows.
+- No layout to measure (headless DOM, `display: none`, detached) -> falls back to 3 lanes.
+
+```typescript
+// Same events, more visible lanes:
+calendar.style.height = '40rem';
+```
+
+## Sizing In A Constrained Host
+
+The month fits its own host box — the bottom weeks are not clipped.
+
+- Host height is **auto** (default): week rows take the square baseline
+  (`100cqw / 7`), and a busy row grows by its lane reservation. The host's
+  height is whatever that adds up to.
+- Host height is **larger** than that: the six rows share the surplus and the
+  lane budget grows with them.
+- Host height is **smaller** (`height`, `max-height`, `aspect-ratio`, a sized
+  flex/grid parent): the rows are capped at their equal share of the room under
+  the header, so all six weeks stay inside the box. The lane budget follows the
+  compressed row — events that no longer fit collapse into the "+N more" chip
+  instead of being drawn outside their cell, and a row too short for even one
+  lane shows the chip alone.
+
+Limits:
+- Measures its OWN box only. An ancestor that clips/scrolls while the calendar's
+  height stays auto (fixed wrapper + `overflow:hidden`, flex item without
+  `min-height:0`) is undetectable — constrain the calendar, not the wrapper.
+- Row floor = the cell's own padding + rules (~17px default). Under a ~200px
+  host the grid overflows again rather than stacking week over week.
+- `view="week"` / `view="day"` keep their own taller row minimums; not capped.
+
+Authoring note: a month grid is a header, a weekday strip and six square-ish
+week rows, so its natural box is TALLER than it is wide. `aspect-ratio: 1` on
+the host is not a neutral size hint — it asks the grid to lose ~1.5 week rows.
+Constrain the width and let the height follow:
+
+```html
+<snice-calendar style="min-width: 360px; max-width: 26rem; width: 100%"></snice-calendar>
+```
+
 ## Keyboard Navigation
 
 - Arrow keys: navigate dates

package/docs/ai/components/code-block.md

@@ -71,6 +71,10 @@ cb.code = 'const x = 1;';
 
 Grammar-based: `format="pretty"` (grammars: json, typescript, css, snice)
 
+- Preserve author line breaks and blank lines; renormalize leading indentation; space rules apply within a line
+- Rule-driven breaks (after `;`, before `}`) fire only where no author break exists; suppressed inside `()`/`[]`; closers break only when their group is multi-line
+- One-liners (e.g. minified JSON) still pretty-print
+
 Imperative: `setFormatter(fn)` overrides grammar formatters
 
 ```typescript

package/docs/ai/components/doc.md

@@ -63,7 +63,7 @@ doc.downloadAs('markdown', 'my-doc.md');
 
 ## Icon Sets
 
-- `default` - Text labels and emoji
+- `default` - Text labels and embedded SVG icons
 - `material` - Material Symbols Outlined (load font in document)
 - `fontawesome` - Font Awesome 6 solid (load font in document)
 - Fonts cascade from light DOM into shadow DOM

package/docs/ai/components/progress.md

@@ -39,6 +39,7 @@ Circular: `base`, `circle`, `circle-bg`, `circle-bar`, `label`
 --progress-radius: 4px;
 --progress-bg: var(--snice-color-border, rgb(226 226 226));
 --progress-color: var(--snice-color-primary, rgb(37 99 235));
+--progress-track-opacity: 0.2;  /* circular track ring; raise to 1 on dark surfaces — 0.2 of any color vanishes on near-black */
 --progress-animation-duration: 1.5s;
 ```
 

package/docs/ai/components/receipt.md

@@ -139,5 +139,5 @@ receipt.taxes = [
 - Subtotal auto-computed from items if not set
 - Total auto-computed as subtotal + tax - discount + tip if not set
 - `taxes` array overrides single `tax` property
-- SKU, notes, per-item discounts only in `detailed` variant
+- SKU, notes, per-item discount lines only in `detailed` variant; an item `discount` still reduces the subtotal in every variant
 - Print styles included for all variants

package/docs/ai/components/table.md

@@ -14,13 +14,14 @@ striped:boolean=false; searchable:boolean=false; filterable:boolean=false; sorta
 hoverable:boolean=true; clickable:boolean=false; list:boolean=false; loading:boolean=false; pagination:boolean=false; virtualize:boolean=false; editable:boolean=false; columnResize:boolean=false; headerFilters:boolean=false; // attrs column-resize/header-filters
 quickFilter:boolean=false; rowReorder:boolean=false; columnReorder:boolean=false; columnMenu:boolean=false; lazyLoad:boolean=false; // attrs quick-filter/row-reorder/column-reorder/column-menu/lazy-load
 mode: 'local'|'remote' = 'local';
-columns:ColumnDefinition[]=[]; data:any[]=[]; currentSort:{column:string;direction:'asc'|'desc'}[]=[]; selectedRows:number[]=[]; // JS-only; selectedRows are raw-data indices
+columns:ColumnDefinition[]=[]; data:any[]=[]; currentSort:{column:string;direction:'asc'|'desc'}[]=[]; selectedRows:number[]=[]; // JS-only; selectedRows are raw-data indices, re-resolved to the same row objects when `data` is reordered (local sort, reordered re-delivery)
 listRenderer:((row,index)=>string|HTMLElement)|null=null; // JS-only; full-width custom rows in list mode
 searchText:string=''; searchDebounce:number=500; // searchText JS-only; attr search-debounce
 selectionMode:'none'|'single'|'multiple'='multiple'; selector:string=''; selectorOptions:{value:string;label:string}[]=[]; // attr selection-mode; options JS-only
 groupBy:string|string[]=''; groupDefaults:{expanded?:boolean}={}; // JS-only
 paginationMode:'client'|'server'='client'; pageSize:number=10; currentPage:number=1; totalItems:number=0; pageSizes:number[]=[10,25,50,100]; // attrs pagination-mode/page-size/current-page/total-items; pageSizes JS-only
 rowHeight:number=48; virtualBuffer:number=200; editMode:'cell'|'row'='cell'; density:'compact'|'standard'|'comfortable'='standard'; // attrs row-height/virtual-buffer/edit-mode
+columnFit:'scroll'|'squish'='scroll'; // attr column-fit
 lazyLoadThreshold:number=200; // lazy-load-threshold, px
 // <snice-column>; camelCase properties reflect to matching kebab-case attributes unless marked JS-only
 key:string=''; label:string=''; type:ColumnType='text'; align:'left'|'center'|'right'='left'; width:string=''; aggregate?:Aggregator; // custom function JS-only
@@ -37,7 +38,7 @@ interface CellProps {value:any;align:'left'|'center'|'right';type:string;column:
 class TextCell {multiline:boolean=false;maxLines?:number} // max-lines
 class NumberCell {decimals:number=0;thousandsSeparator:boolean=false;prefix:string='';suffix:string='';negativeStyle:'parentheses'|'red'|'minus'='minus';highlight:boolean=false} // thousands-separator, negative-style
 class CurrencyCell {decimals:number=2;thousandsSeparator:boolean=true;currency:string='USD';currencyDisplay:'symbol'|'code'|'name'='symbol';locale:string='en-US';negativeStyle:'parentheses'|'red'|'minus'='red';highlight:boolean=false} // thousands-separator, currencydisplay, negative-style
-class DateCell {dateFormat:'short'|'medium'|'long'|'full'|'custom'='short';customFormat?:string;locale:string='en-US';relativeTime:boolean=false;showTime:boolean=false} // date-format, custom-format, relative-time, show-time
+class DateCell {dateFormat:'short'|'medium'|'long'|'full'|'custom'='short';customFormat?:string;locale:string='en-US';relativeTime:boolean=false;showTime:boolean=false} // date-format, custom-format, relative-time, show-time; date-only values ('2026-03-15','2026-03','2026') are calendar days read at LOCAL midnight — same day in every timezone, in display/export/filters; values with a time (…T10:00, …Z, epoch, Date) stay instants; a date-only filter bound spans the whole day, so before/onOrBefore/after/onOrAfter agree with `is` (onOrBefore '2026-03-15' keeps '2026-03-15T09:00'); impossible days ('2026-02-30','2026-13-01') are rejected, not rolled over, and render as the raw value
 class BooleanCell {trueValue:string='true';falseValue:string='false';useSymbols:boolean=true;trueSymbol:string='svg';falseSymbol:string='svg'} // true-value, false-value, use-symbols, true-symbol, false-symbol
 class PercentageCell {decimals:number=2;showTrend:boolean=false;trendValue:number|null=null;colorize:boolean=true} // attrs showtrend/trendvalue (no hyphens)
 class SparklineCell {chartType:'line'|'bar'|'area'='line';color:string='var(--snice-color-primary)';width:number=80;height:number=24;showDots:boolean=false;showBaseline:boolean=false;strokeWidth:number=1.5;minValue?:number;maxValue?:number;data:number[]=[]} // assign data in JS; color/width/height attrs unchanged; other camel names use explicit kebab attrs
@@ -63,46 +64,45 @@ interface ColumnDefinition {
 }
 type Aggregator='sum'|'avg'|'min'|'max'|'count'|((values:any[],rows:any[])=>any);
 type NumberFormat={decimals?:number;thousandsSeparator?:boolean;prefix?:string;suffix?:string;negativeStyle?:'parentheses'|'red'|'minus'}; type DateFormat={format?:'short'|'medium'|'long'|'full'|'custom';customFormat?:string;locale?:string};
-type BooleanFormat={trueValue?:string;falseValue?:string;useSymbols?:boolean;trueSymbol?:string;falseSymbol?:string}; type RatingFormat={max?:number;symbol?:string;emptySymbol?:string;color?:string};
-type ProgressFormat={max?:number;showPercentage?:boolean;color?:string;colorize?:boolean;backgroundColor?:string;height?:string}; type SparklineFormat={type?:'line'|'bar'|'area';color?:string;width?:number;height?:number;showDots?:boolean;showBaseline?:boolean;strokeWidth?:number;minValue?:number;maxValue?:number};
-type PercentageFormat={decimals?:number;showTrend?:boolean;trendValue?:number|null;colorize?:boolean}; type PhoneFormat={phone?:string;displayText?:string;showIcon?:boolean;format?:boolean;country?:string};
-type StatusFormat={status?:string;label?:string;showDot?:boolean;variant?:'online'|'offline'|'busy'|'away'|'custom'}; type TagFormat={variant?:string};
-type ActionsFormat={actions:ActionButton[]}; type ActionButton={action:string;label?:string;icon?:string;variant?:'primary'|'secondary'|'danger'|'success';title?:string;disabled?:boolean};
-type LinkFormat={href?:string;target?:string;external?:boolean;icon?:string;text?:string}; type EmailFormat={email?:string;showIcon?:boolean;displayText?:string};
-type ColorFormat={color?:string;size?:'small'|'medium'|'large';displayFormat?:'hex'|'rgb'|'hsl'|'name';showSwatch?:boolean;showHex?:boolean;showRgb?:boolean;swatchSize?:'small'|'medium'|'large'};
-type CurrencyFormat={currency?:string;locale?:string;display?:'symbol'|'code'|'name';currencyDisplay?:'symbol'|'code'|'name';decimals?:number;thousandsSeparator?:boolean;negativeStyle?:'parentheses'|'red'|'minus'};
+type BooleanFormat={trueValue?:string;falseValue?:string;useSymbols?:boolean;trueSymbol?:string;falseSymbol?:string}; type RatingFormat={max?:number;symbol?:string;emptySymbol?:string;color?:string}; type ProgressFormat={max?:number;showPercentage?:boolean;color?:string;colorize?:boolean;backgroundColor?:string;height?:string}; type SparklineFormat={type?:'line'|'bar'|'area';color?:string;width?:number;height?:number;showDots?:boolean;showBaseline?:boolean;strokeWidth?:number;minValue?:number;maxValue?:number};
+type PercentageFormat={decimals?:number;showTrend?:boolean;trendValue?:number|null;colorize?:boolean}; type PhoneFormat={phone?:string;displayText?:string;showIcon?:boolean;format?:boolean;country?:string}; type StatusFormat={status?:string;label?:string;showDot?:boolean;variant?:'online'|'offline'|'busy'|'away'|'custom'}; type TagFormat={variant?:string};
+type ActionsFormat={actions:ActionButton[]}; type ActionButton={action:string;label?:string;icon?:string;variant?:'primary'|'secondary'|'danger'|'success';title?:string;disabled?:boolean}; type LinkFormat={href?:string;target?:string;external?:boolean;icon?:string;text?:string}; type EmailFormat={email?:string;showIcon?:boolean;displayText?:string};
+type ColorFormat={color?:string;size?:'small'|'medium'|'large';displayFormat?:'hex'|'rgb'|'hsl'|'name';showSwatch?:boolean;showHex?:boolean;showRgb?:boolean;swatchSize?:'small'|'medium'|'large'}; type CurrencyFormat={currency?:string;locale?:string;display?:'symbol'|'code'|'name';currencyDisplay?:'symbol'|'code'|'name';decimals?:number;thousandsSeparator?:boolean;negativeStyle?:'parentheses'|'red'|'minus'};
 type ImageFormat={src?:string;fallback?:string;shape?:'rounded'|'square'|'circle';variant?:'rounded'|'square'|'circle';size?:'small'|'medium'|'large';alt?:string;lazy?:boolean}; type JsonFormat={maxDepth?:number;expanded?:boolean;collapsed?:boolean;showToggle?:boolean};
 type LocationFormat={address?:string;latitude?:string|number;longitude?:string|number;showMapLink?:boolean;mapProvider?:'google'|'openstreetmap'|'apple';showIcon?:boolean;lat?:number;lng?:number};
 type CellStyle={backgroundColor?:string;color?:string;fontWeight?:'normal'|'bold'|'lighter';fontStyle?:'normal'|'italic';fontSize?:string;textDecoration?:'none'|'underline'|'line-through'}; type ConditionalFormat={condition:(value:any,row?:any)=>boolean;style?:CellStyle;className?:string};
 ```
 
-- `table.columns =`/`table.data =` rerender; `setData()` is non-eager, so call `renderBody()` when unpaired.
+- `table.columns =`/`table.data =` rerender on EVERY assignment — identity is not consulted, so re-assigning the SAME array reference after mutating it in place (`rows.push(r); table.data = rows`) rerenders. Tradeoff: a truly redundant assignment costs a render (coalesced per microtask, so a burst still paints once). `setData()` is non-eager, so call `renderBody()` when unpaired. A `columns` assignment is a NEW CONFIGURATION, not a patch: the assigned array owns painted order, `pinned`, `width` and the column set (undeclared keys are dropped from the model; a re-declared key returns visible), which also discards user column state (drag-resize, manual reorder, `setColumnVisible()` hides) for the columns it re-declares — on EVERY assignment including a same-reference one, so mutating the published definitions is NOT an escape hatch; keep user column state by not re-assigning `columns` and using `setColumnVisible()`/`moveColumn()`/`pinColumn()`/`unpinColumn()` instead. A delivery under a non-empty `currentSort` renders sorted (local; remote keeps the server order). Rows recycle by identity but repaint when their own field values change, so an in-place patch + re-delivery updates that row — shallow compare, so a mutation inside a nested object value needs a new row object.
 - `searchable` filters locally or requests remotely; `quickFilter` shows a model-backed input; `filterable` is the legacy remote selector.
-- Currency uses `snice-cell-currency`. Formatter/valueFormatter, tooltip, base/conditional styles, all declared format aliases, object progress/JSON/sparkline values, sparkline baselines, and already-percent semantics work across Table/declarative/standalone paths.
-- `rowReorder`, `columnReorder`, `lazyLoad`, and its threshold are post-mount reactive. List renderers execute in list mode. Density emits `density-change`.
-- Limits: pagination shows "Showing 1–25 of 60" or numbered `aria-label="Page N"` (no "Page X of Y"); remote has a 150ms debounce, re-requests only on `currentPage`/`currentSort`/`pageSize`, and keeps rows on a failed reload (⚠️ row + empty-state only with no data); local sort/search are client-side on `data` only.
+- Currency uses `snice-cell-currency`. Formatter/valueFormatter, tooltip, base/conditional styles, all declared format aliases, object progress/JSON/sparkline values, sparkline baselines, and already-percent semantics work across Table/declarative/standalone paths. Display pipeline: `valueGetter` -> `formatter` (wins) -> `valueFormatter` (fallback), on every path — cells, aggregate footers, `<snice-row>`, CSV/clipboard export; a column declaring either formatter renders through `snice-cell-text` (keeping its type's alignment) and the cell's `value` property/attribute IS the display value — except the tree group column, whose resolved label is plain text beside the indent/chevron (no typed cell, so no `value` attribute). An empty row value (null, or a field the row never carried) falls back to the typed cell's own empty value — `false` boolean, `0` rating/progress/duration/filesize, `null` JSON, `''` otherwise — so an absent boolean never reads as `true` and an absent progress never reads as `{}` (table-rendered cells; a declarative `<snice-row>` hands the cell the empty value unchanged).
+- `virtualize` windows the body but keeps every zero-row state: loading spinner, `⚠️` load error, and the `empty-state` slot clone (or the default "No data" placeholder) all render on the virtual path too.
+- Zero-row `loading` renders `<div class="table-loading-state" role="status" aria-live="polite">` = medium `snice-progress` + a `.table-loading-label` reading `Loading…`. With rows present the `loading-overlay` part replaces it and carries `role="status"`/`aria-label="Loading…"`. Both raise `--progress-track-opacity` so the track reads on dark surfaces.
+- `type:'accounting'` = currency notation: symbol + grouping + parenthesised negatives, positives padded with one NBSP for column alignment. Defaults 2 decimals / grouping on / USD / en-US. `numberFormat.decimals|thousandsSeparator` and `currencyFormat.currency|locale|currencyDisplay` override; `numberFormat.prefix|suffix` replaces the symbol. `-12840.5` -> `($12,840.50)`. Generic `<snice-cell>` writes an inline `text-align` only when `align` is declared, so an undeclared cell keeps its TYPE's alignment from snice-cell.css (numeric types right, boolean/rating/sparkline centre).
+- `rowReorder`, `columnReorder`, `lazyLoad`, and its threshold are post-mount reactive. List renderers execute in list mode. An ACTIVE `listRenderer` (needs `list` too) also suppresses the columnar header — column-group row, per-column `<th>`, and header-filter row all drop, since a card row has no column geometry; tool-column headers stay, so `selectable` keeps select-all. Clearing `listRenderer` or `list` restores the header; `list` alone (no renderer) keeps columnar cells AND its header. With no header to click, list-mode sorting runs through the toolbar (`setToolbar({showSort:true})`) or `toggleSort()`/`currentSort`. Density emits `density-change`. `selectable` and `selectionMode` are post-mount reactive too: either one rebuilds header + body, so the checkbox tool column appears/disappears in both.
+- Selection is anchored to the row, not the position: a local sort or a re-delivery of the same row objects in another order re-resolves `selectedRows`, so `getSelectedData()` and the highlight stay on the same rows. A different row set keeps the raw-index semantics.
+- Limits: pagination shows "Showing 1–25 of 60" or numbered `aria-label="Page N"` (no "Page X of Y"); remote has a 150ms debounce, re-requests only on `currentPage`/`currentSort`/`pageSize` (the re-request supersedes any in-flight request WHEN THE CHANGE IS MADE, not when the debounce fires — a response landing inside the window is discarded, and a superseded failure is silent: only the newest request reports `table-load-error`), and keeps rows on a failed reload (⚠️ row + empty-state only with no data). The error state (⚠️ row + `table--error` class) describes the last delivery ATTEMPT and clears on ANY arriving dataset — successful re-request, `setData()`, or a `table.data =` assignment (including `[]`, which then shows the empty state, not the stale error) — the assignment need NOT be a new array (same-reference clears it too), a drag row-reorder republishes the same rows and does NOT clear, and an already-in-flight request still reports its own failure when it settles. Local sort/search are client-side on `data` only. Client pagination re-clamps `currentPage` to the new last page when a filter or a shorter re-delivery leaves it past the end (an empty set keeps the declared page), so the body always shows the rows the summary claims.
 
 ## Methods
 
 - `getTableConfig()` - Request/apply controller config; `getTableData()` - request/apply current rows; `setData(data)` - non-eager bulk load; `setColumns(columns)` - assign and schedule both renders
 - `renderControls()` - Render legacy controls; `renderHeader()` - render headers/tools/filters; `renderSortableHeader(column)` - return sortable-header HTML; `renderBody()` - render display model; `renderPagination()` - render pager
 - `createCellElement(column,value,row?)` - Build rendered cell; `getCellTagName(type)` - resolve runtime cell tag
-- `getSelectedData()` - Resolve raw selected indices; `setSelectabilityCheck(fn)` - install row predicate; `updateRowSelectionState()` - sync rows; `updateSelectAllState()` - sync select-all
-- `toggleSort(key,multi?)` - Cycle direction; `setSortComparator(key,fn)` - install comparator; `goToPage(page)` - clamp/navigate; `setPageSize(size)` - resize/reset page
+- `getSelectedData()` - Resolve raw selected indices; `setSelectabilityCheck(fn)` - install row predicate; `updateRowSelectionState()` - sync rows (keyed by each row's data index, so group/aggregate/spacer/filler rows are never marked selected); `updateSelectAllState()` - sync select-all (also runs on every body render, so a new row set re-derives checked/indeterminate)
+- `toggleSort(key,multi?)` - Cycle direction; `setSortComparator(key,fn)` - install comparator (receives valueGetter-derived values); `goToPage(page)` - clamp/navigate; `setPageSize(size)` - resize/reset page
 - `setColumnFilter(column,operator,value)` - Set one filter; `removeColumnFilter(column)` - remove it; `setQuickFilter(text)` - global search; `setFilterModel(model)` - replace model; `getFilterModel()` - read model; `clearAllFilters()` - clear all
 - Filter operators: text `contains/notContains/equals/notEquals/startsWith/endsWith/isEmpty/isNotEmpty`; number `eq/neq/gt/gte/lt/lte/isEmpty/isNotEmpty`; date `is/isNot/before/onOrBefore/after/onOrAfter/isEmpty/isNotEmpty`; boolean `isTrue/isFalse`
 - `setColumnVisible(key,visible)` - Set visibility; `showAllColumns()` - show all; `hideAllColumns()` - hide hideable; `getColumnVisibility()` - read map; `pinColumn(key,side)` - pin; `unpinColumn(key)` - unpin
-- `autoSizeColumn(key)` - Measure one; `autoSizeAllColumns()` - measure all; `moveColumn(key,index)` - move; `setColumnGroups(groups)` - add grouped headers
-- `scrollToRow(index)` - Reveal data row; `scrollToColumn(key)` - reveal header; `getScrollPosition()` - read `{top,left}`; `setRowHeight(px)` - set fixed height; `setRowHeightCallback(fn)` - set rendered/virtual height
+- `autoSizeColumn(key)` - Fit one column to its content; `autoSizeAllColumns()` - fit all. Both measure the rendered header + body under content-driven layout, so they SHRINK as well as grow, and repaint header AND body with the measured width. `moveColumn(key,index)` - move; `setColumnGroups(groups)` - add grouped headers
+- `scrollToRow(index)` - Reveal data row (recomputes the virtual window in the same call — a programmatic scroll fires no `scroll` event, so the row is in the DOM on return); `scrollToColumn(key)` - reveal header; `getScrollPosition()` - read `{top,left}`; `setRowHeight(px)` - set fixed height; `setRowHeightCallback(fn)` - set rendered/virtual height
 - `startEdit(row,key)` - Start cell/row edit; `commitEdit()` - validate/commit; `cancelEdit()` - cancel; `setCellEditableCheck(fn)` - install predicate. Parsers/setters receive the real row; setters may return a value or row
 - `exportCSV(options?)` - Download filtered raw data; `printTable(options?)` - print visible text with toolbar/footer/checkbox options; `copyToClipboard(options?)` - copy formatted (default) or raw filtered data; `toggleFullscreen()` - toggle native/fallback fullscreen
-- `setToolbar(options)` - Install search/sort/filter/export/fullscreen UI; `setListViewRenderer(fn)` - render full-width custom list rows
+- `setToolbar(options)` - Install search/sort/filter/export/fullscreen UI, `{showSearch?,showSort?,showFilter?,showExport?,searchPlaceholder?}`; fullscreen always appears; sort/filter buttons edit the header/menu models; `setListViewRenderer(fn)` - render full-width custom list rows
 - `setDetailPanel(options)` - Configure content/height/lazy lifecycle/icons; `expandRow(i)` - expand; `collapseRow(i)` - collapse; `toggleRowExpansion(i)` - toggle; `expandAllRows()` - expand all; `collapseAllRows()` - collapse all
-- `setTreeData(options)` - Configure path hierarchy; `expandTreeNode(key)` - expand; `collapseTreeNode(key)` - collapse; `toggleTreeNode(key)` - toggle; `expandAllTreeNodes()` - expand all; `collapseAllTreeNodes()` - collapse all
+- `setTreeData(options)` - Configure path hierarchy; `expandTreeNode(key)` - expand; `collapseTreeNode(key)` - collapse; `toggleTreeNode(key)` - toggle; `expandAllTreeNodes()` - expand all; `collapseAllTreeNodes()` - collapse all. Every skipped path level becomes a gap node (`['Eng','Team','Alice']` alone renders Eng+Team+Alice); `defaultExpansionDepth` seeds the STARTING expansion once, so a full collapse sticks; the group column runs the normal display pipeline (`renderCell` > `formatter` > `valueFormatter`) beside the indent/chevron; tree rows render detail panels when `setDetailPanel()` is configured (gap nodes, index `-1`, never do)
 - `pinRowTop(row)` - Pin above; `pinRowBottom(row)` - pin below; `unpinRow(row)` - unpin same object; `clearPinnedRows()` - clear both areas
 - `<snice-column>`: `setFormatter(fn)` - set formatter; `addConditionalFormat(rule)` - append; `removeConditionalFormat(i)` - remove; `clearConditionalFormats()` - clear; `getColumnDefinition()` - build definition
 - `<snice-row>`: `select()` - select if allowed; `deselect()` - deselect; `focusRow()` - focus/scroll; `getCellValue(key)` - read; `setCellValue(key,value)` - update; `getCellElement(key)` - find cell; `updateCells()` - reconfigure cells; `highlight(ms?)` - temporary highlight
-- Toolbar options: `{showSearch?,showSort?,showFilter?,showExport?,searchPlaceholder?}`; fullscreen always appears; sort/filter buttons edit the header/menu models.
 - Remote `table/data` payload: `{search,sort,filter,selector,page?,pageSize?}`; response: `{data,totalItems?}`. Automatic initial request requires `mode="remote"`; page requests also require `pagination-mode="server"`.
 - CSV/clipboard resolve raw selected identities before intersecting filters, so active filters cannot retarget selection.
 
@@ -121,16 +121,18 @@ type CellStyle={backgroundColor?:string;color?:string;fontWeight?:'normal'|'bold
 
 ## Slots
 
-- `<snice-table>`: `columns`, `rows`, `header`, `empty-state` (cloned into the shadow body on EACH zero-row render — the slotted original is only a template); no default slot. `<snice-column>`: default inert content slot. Cells: no slots.
-- CDN Table bundle includes column, row, and cell dependencies. Grouping/aggregation upgrades declarative rows to the native table model.
+- `<snice-table>`: `columns`, `rows`, `header`, `empty-state` (cloned into the shadow body on EACH zero-row render, virtualized or not — the slotted original is only a template); no default slot. `<snice-column>`: default inert content slot. Cells: no slots. CDN Table bundle includes column, row, and cell dependencies. Grouping/aggregation upgrades declarative rows to the native table model.
 
 ## CSS Parts
 
-- `<snice-table>`: `body`, `superheader`, `controls`, `toolbar`, `pagination`, `loading-overlay` (refetch spinner while `loading` with rows present), `row` (each native body row), `cell` (each native body cell), `filter-button` (column filter trigger), `sort-indicator` (sort direction); `<snice-row>`: `container`, `checkbox-cell`, `cell`; cells: `content`; actions: `action-button`; JSON: `toggle`; tag: `tag`; link/email/phone/location: `link`
+- `<snice-table>`: `body`, `superheader`, `controls`, `toolbar`, `pagination`, `loading-overlay` (refetch spinner while `loading` with rows present), `row` (each native body row), `cell` (each native body cell — the inert filler that pads a body shorter than its host, virtualized or not, is neither and exposes no part), `filter-button` (column filter trigger), `sort-indicator` (sort direction); `<snice-row>`: `container`, `checkbox-cell`, `cell`; cells: `content`; actions: `action-button`; JSON: `toggle`; tag: `tag`; link/email/phone/location: `link`
+- `column-fit` (default `scroll`) = the fitting policy. `scroll`: `minWidth` wins, `.table-frame` scrolls horizontally when the columns no longer fit. `squish`: the FRAME wins — `minWidth` relaxes to a 24px floor, every visible column shares the frame width, cell content AND header labels ellipsise (typed cells too: squish relaxes their 100px floor via `--snice-table-cell-min-width`, without which they clip mid-glyph), `.table-frame` gets `overflow-x:hidden`, and the rightmost column edge sits on the frame's inner edge at any width. Squish resize is allowed and REBALANCES: the dragged column keeps its width (capped so the rest can still sit on the floor) and the others scale to fill what is left. Declared widths are honoured while an unsized column can absorb the difference; when the authored widths alone overflow, every column is scaled by the same factor. Reactive — assigning `columnFit` re-fits the painted columns. Use squish for a table inside a card/tile/split pane; use scroll for a wide dataset (pinned columns only pay off when something scrolls).
+- Column width: a column that declares no `width` SHARES the frame — grown or shrunk on every render and frame resize, floored at `minWidth` (default 50), after which the frame scrolls instead of collapsing. A declared `width`, a drag-resize, and an auto-size are authored widths and are never refitted. Pinned cells carry `pinned-cell` + `pinned-cell--left|right`; the inner-most column per side adds `pinned-cell--edge` (2px divider + shadow) and its header a `.pin-indicator` pin glyph, so pinning reads even when nothing scrolls.
+- Height fill: the filler only consumes space the frame ALREADY has. A content-driven host (`:host{height:100%}` against an auto/max-content parent — stretched grid/flex item, plain block) would make the filler an input to its own resize trigger, so the table applies it, verifies the frame kept its height, and hands back any self-caused growth (partial filler, or none). Size the host (explicit height / flex or grid track / sized ancestor) to get a full-height grid.
 
 ## CSS Custom Properties
 
-- `--snice-table-body-bg`, `--snice-table-group-header-bg`, `--snice-table-group-header-color`, `--snice-table-group-count-bg`, `--snice-table-group-count-color`, `--snice-table-aggregate-bg`, `--snice-table-aggregate-border-color`, `--snice-table-aggregate-color`, `--snice-table-aggregate-label-color`, `--snice-table-cell-padding`, `--snice-table-cell-border` (vertical; `none` drops grid lines), `--snice-table-row-border` (horizontal)
+- `--snice-table-stripe-bg` (`striped` row tint; defaults to `--snice-color-overlay-stripe`, an alpha tint tuned per theme), `--snice-table-body-bg`, `--snice-table-group-header-bg`, `--snice-table-group-header-color`, `--snice-table-group-count-bg`, `--snice-table-group-count-color`, `--snice-table-aggregate-bg`, `--snice-table-aggregate-border-color`, `--snice-table-aggregate-color`, `--snice-table-aggregate-label-color`, `--snice-table-cell-padding`, `--snice-table-cell-border` (vertical; `none` drops grid lines), `--snice-table-row-border` (horizontal), `--snice-table-cell-min-width` (typed-cell width floor, default `6.25rem`; squish sets it to `0`)
 
 ## Basic Usage
 
@@ -141,10 +143,7 @@ table.data = employees;
 table.setToolbar({showSearch:true,showSort:true,showFilter:true,showExport:true});
 ```
 
-## Keyboard Navigation
+## Keyboard & Accessibility
 
 - Grid: arrows, Home/End, Page Up/Down; Enter edits; Space/Shift+Space toggles selection; Ctrl/Cmd+A selects filtered selectable rows. Group/tree/detail buttons: Tab then Enter/Space.
-
-## Accessibility
-
-- Native table uses ARIA grid roles, live counts, roving focus, `aria-sort`, and `aria-selected`; group/tree/detail controls expose labels/`aria-expanded`, and group selection supports mixed state.
+- Native table uses ARIA grid roles, live counts, roving focus, `aria-sort`, and `aria-selected`; group/tree/detail controls expose labels/`aria-expanded`, and group selection supports mixed state. `aria-selected="true"` is written with `data-selected` on every selection path, including click/checkbox/select-all deltas — not only on a full body render.

package/docs/ai/components/theme.md

@@ -56,6 +56,7 @@ CSS-only design token system. No component -- just import the stylesheet.
 --snice-color-overlay-hover          /* hsl(0 0% 0% / 0.04) — hover tint over any surface */
 --snice-color-overlay-selected       /* hsl(primary / 0.08) — selected row/item tint */
 --snice-color-overlay-selected-hover /* hsl(primary / 0.12) — selected + hovered */
+--snice-color-overlay-stripe         /* hsl(0 0% 0%/.02) light, hsl(0 0% 100%/.11) dark — zebra row tint; dark needs the bigger step */
 ```
 
 ### Spacing

package/docs/ai/events.md

@@ -317,6 +317,36 @@ cancels an older timer and dispatches the new result immediately. Throttle
 trailing detail is latest-wins; its deadline is last actual dispatch + the
 newly resolved interval.
 
+### cancelable — suppressible default actions
+
+`cancelable` is an `EventInit` field, so `@dispatch('x', { cancelable: true })`
+DOES produce a cancelable event and listeners can call `preventDefault()`.
+
+But the decorated method returns the **detail**, not `dispatchEvent`'s boolean,
+so the component cannot see whether the event was cancelled. A component with a
+default action to suppress must dispatch by hand and read the result:
+
+```typescript
+// ❌ Cancelable, but the component can never act on the cancellation
+@dispatch('more-click', { cancelable: true })
+private emitMore(date: Date) { return { date }; }
+
+// ✅ Default action the app can cancel
+private emitMore(date: Date): boolean {
+  return this.dispatchEvent(new CustomEvent('more-click', {
+    detail: { date }, bubbles: true, composed: true, cancelable: true,
+  }));
+}
+
+private onChipClick(date: Date) {
+  if (!this.emitMore(date)) return;   // preventDefault() -> app owns it
+  this.openBuiltInPanel(date);
+}
+```
+
+In the library: `snice-link`'s `navigate`, `snice-stepper`'s `step-change`,
+`snice-calendar`'s `calendar-more-click`.
+
 ### scope — dispatch target
 
 Default: `this.dispatchEvent(event)` — event originates from the host element. `scope` redirects the dispatch to another target so the event behaves as if it originated there. Use with `@on({ scope })` to express cross-cutting events without bubbling.

package/docs/ai/theme.md

@@ -58,6 +58,7 @@ Modern syntax with alpha: `hsl(0 0% 0% / 0.15)` (not `hsla(0, 0%, 0%, 0.15)`)
 --snice-color-overlay-hover: hsl(0 0% 0% / 0.04);
 --snice-color-overlay-selected: hsl(var(--snice-color-blue-500) / 0.08);
 --snice-color-overlay-selected-hover: hsl(var(--snice-color-blue-500) / 0.12);
+--snice-color-overlay-stripe: hsl(0 0% 0% / 0.02);   /* dark: hsl(0 0% 100% / 0.11) */
 ```
 
 ## Layers (z-index)