@rcarls/rc-list 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,182 @@
 # @rcarls/rc-list
 
+## 0.7.0
+
+### Minor Changes
+
+- 079e025: Standardize component styling contracts for the breaking 0.7 release.
+
+  BREAKING CHANGE: Rename the Markdown editor's `--rme-*` properties to
+  `--rc-markdown-editor-*`, `--rc-app-bar-background` to `--rc-app-bar-bg`,
+  `--rc-textarea-radius` to `--rc-textarea-border-radius`, the transfer-list
+  `--rc-transfer-list-panel-*` properties to `--rc-transfer-list-listbox-*`,
+  `--rc-chip-group-webkit-scrollbar-display` to
+  `--rc-chip-group-scrollbar-display`, and `--rc-text` to `--rc-field-text`.
+  Compatibility aliases are intentionally not provided.
+
+  BREAKING CHANGE: Replace `--rc-select-chip-padding-inline` and
+  `--rc-combobox-chip-padding-inline` with explicit `*-padding-inline-start` and
+  `*-padding-inline-end` tokens. Generated removable chips now reserve the full
+  remove target and its edge offset, so their indicator cannot overlap label text.
+
+  Add canonical app-bar elevation, transfer-list listbox radius, and textarea
+  line-action tokens. Add logical `rc-chip` inline-padding properties so themes
+  can implement Material's icon-aware spacing without overriding authored child
+  styles. Make `rc-field` consume the shared semantic token layer,
+  and place the `rc-chip` and `rc-search-bar` light-DOM structural styles in the
+  `rc-base` cascade layer so normal consumer rules override them.
+
+  Prevent decorative, `aria-hidden` trailing list content from intercepting a
+  whole-row action target, and keep segmented-list item geometry from leaking
+  into nested standard lists.
+
+  Remove unused Material navigation-rail toggle tokens and obsolete list-item
+  theme tokens. Register the segmented-button private theme seam and enforce
+  token ownership, documentation, removed-name, selector-budget, and cascade
+  layer contracts through the component architecture audit.
+
+- 6ec0857: Add `ordered` to `rc-list`. Visible items in an ordered list receive `aria-posinset` and
+  `aria-setsize` so assistive technology reports their position; no counters render, and authored
+  positions from a rendered slice of a longer list are kept.
+
+  Add an expandable `details` region to `rc-list-item`. A button marked
+  `data-rc-list-item-toggle` toggles it; the item wires `aria-expanded`, `aria-controls`, and the
+  region's `hidden` state, supports controlled `expanded` and uncontrolled `default-expanded`
+  state, and fires `rc-list-item-toggle`. Material styles the region as list supporting text.
+
+- 54d9ead: Localize every component's built-in text. Button names, role
+  descriptions, announcements, and default labels now resolve per key from
+  the element's `messages` property, then from text registered with
+  `registerMessages(locale, catalog)` in `@rcarls/rc-common`, then from the
+  English defaults. The locale is the element's own `lang`, else
+  `<html lang>`; an ancestor's `lang` is ignored, because it usually marks
+  content rather than the interface. Components re-render when that locale
+  changes or new text is registered. `RcMessageCatalog` types the catalog,
+  and each package adds its scope to it.
+
+  Numbers a component formats as text follow the same locale:
+  `rc-progress`'s default percentage and `rc-splitter`'s `aria-valuetext`
+  use `Intl.NumberFormat`. `TypeaheadController` matches prefixes with an
+  `Intl.Collator`, so case and accents are ignored the way the locale
+  ignores them, and takes a `locale` option. `ItemsCollectionController`'s
+  `setCreateOption(text, label?)` takes the option's visible text from its
+  caller.
+
+  `rc-transfer-list`'s direction arrows are now decorative: screen readers
+  read only the action name, and the arrows turn over in RTL.
+
+  **Breaking:** chrome-text properties are replaced by `messages`. Migrate:
+
+  - `rc-search-bar` `clear-label` / `clearLabel` → `messages.clear`
+  - `rc-adaptive-menu` `overflow-label` / `overflowLabel` → `messages.overflow`
+  - `rc-chip-group` `show-all-label` / `showAllLabel` and `show-less-label` /
+    `showLessLabel` → `messages.showAll` and `messages.showLess`
+  - `rc-select` and `rc-combobox` `dialog-confirm-label` /
+    `dialogConfirmLabel` and `dialog-cancel-label` / `dialogCancelLabel` →
+    `messages.done` and `messages.cancel`
+  - `rc-editor-toolbar` `label` → `messages.toolbar`
+
+  Per-instance names stay attributes, but now default to `undefined` and fall
+  back to a message: `label` on `rc-adaptive-menu`, `rc-chip-group`,
+  `rc-menubar`, and `rc-splitter`; `available-label` and `selected-label`
+  on `rc-transfer-list`; `low-label` and `high-label` on `rc-range-slider`.
+  Read the resolved name from the rendered `aria-label` instead of the
+  property.
+
+- 6e548d9: Several components handle `prefers-reduced-motion: reduce` in their own
+  shadow styles, outside a theme's reach, and refine it the same way the theme
+  layer already does: spatial motion (`translate`, `scale`, `transform`,
+  `inline-size`, `block-size`) goes fully to zero, while effects motion (color,
+  opacity) shortens instead of disappearing.
+
+  `rc-app-bar` zeros its host's hide/show `translate` but shortens the
+  expanded title's fade-in. `rc-disclosure` keeps its panel's expand/collapse
+  zeroed, but its summary/content backstop for a theme-added transition now
+  shortens instead of zeroing it outright. `rc-list-item`'s row and
+  state-layer transition only color and opacity, so the whole sweep shortens.
+  `rc-fab-menu`'s popup mixes `scale` with opacity/overlay/display under one
+  shared duration; reduced motion now zeros the scale and shortens the rest.
+  `rc-switch`'s thumb mixes background-color with inline-size/block-size/
+  transform the same way; the icons and track, which each transition only one
+  kind of property, needed only the zero-or-shorten call. `rc-fab`'s
+  scroll-reveal is opacity/visibility only with no time-based duration to
+  shorten in its scroll-linked path, so reduced motion narrows the scroll
+  window instead of collapsing it to zero; its JS-transition fallback path
+  shortens the same fade rather than removing it. `rc-progress`'s determinate
+  fill transition, previously unguarded under reduced motion, is now zeroed;
+  its indeterminate loop, a continuous sweep with no meaningful shortened
+  form, stays fully stopped rather than shortened.
+
+- c130173: Add pointer and keyboard reordering to `rc-list`.
+
+  Set `reorderable` and give each item a native `<button data-rc-reorder-handle>`. People can drag
+  a handle, and the items it passes shift out of the way while the nearest scroll container
+  scrolls near its edges. On touch and pen, a long press on an item also starts a drag, while
+  movement before activation remains available for scrolling. Or they can focus a handle and use
+  Space, the block-axis arrow keys, Home, End, and Escape. Each step is announced, focus stays on
+  the moved item's handle, and geometry and keys follow the writing mode. `reorderable` implies
+  `ordered`.
+
+  Each committed move fires a cancelable `rc-list-reorder` event with `{ item, from, to }`. Left
+  alone, the list moves the node itself; a framework that renders the items cancels the event and
+  reorders its own data. `reorderMessages` overrides the announcements and the handle hint.
+
+  `rc-common` gains the `ReorderController` behind it and a `LiveAnnouncer` live-region helper.
+  `rc-theme-material` styles the lifted item with the dragged elevation, surface, and state layer,
+  animates the shifting items with standard motion, and presents plain handles as standard icon
+  buttons.
+
+### Patch Changes
+
+- 38cd00c: Convert viewport measurements to local CSS pixels when reordering items,
+  positioning navigation indicators, and clamping anchored popups under CSS zoom.
+  Reorder previews now account for the scroll container's zoom, while anchor
+  corrections settle without repeated overshoot.
+- 5c006de: Ship component CSS minified. Package builds now run the CSS in Lit `css` styles
+  and light-DOM structural styles through Lightning CSS, removing comments and
+  whitespace while keeping source maps that resolve to each template. Rendered
+  styles are unchanged.
+
+  `@rcarls/rc-common` adds `cssText`, an identity tag that marks a plain CSS
+  string for minification. `rc-chip`, `rc-disclosure`, and `rc-accordion` now
+  depend on `@rcarls/rc-common` for it.
+
+- 2dbeccf: Place rows by `aria-posinset` and `aria-setsize` when they carry them, so a
+  virtualized list rendering only a slice gives first- and last-row styling to
+  the set's real ends instead of the ends of the slice.
+- Updated dependencies [e3dfa59]
+- Updated dependencies [50d5610]
+- Updated dependencies [9ee769c]
+- Updated dependencies [1179f24]
+- Updated dependencies [595fe37]
+- Updated dependencies [38cd00c]
+- Updated dependencies [5c006de]
+- Updated dependencies [a6553ff]
+- Updated dependencies [2205478]
+- Updated dependencies [4341311]
+- Updated dependencies [899bb5e]
+- Updated dependencies [25fcfe0]
+- Updated dependencies [51f6403]
+- Updated dependencies [9caca6b]
+- Updated dependencies [b764a3c]
+- Updated dependencies [54d9ead]
+- Updated dependencies [b9175e9]
+- Updated dependencies [c8b762b]
+- Updated dependencies [55e1e7f]
+- Updated dependencies [f1ca82d]
+- Updated dependencies [b87f27b]
+- Updated dependencies [32ebead]
+- Updated dependencies [bfefedd]
+- Updated dependencies [c130173]
+- Updated dependencies [11680b6]
+- Updated dependencies [223d36c]
+- Updated dependencies [7b91a44]
+- Updated dependencies [aa04ead]
+- Updated dependencies [ac65b5b]
+- Updated dependencies [afcfef8]
+- Updated dependencies [11ef1ad]
+  - @rcarls/rc-common@0.7.0
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -34,6 +34,103 @@ input. Links, buttons, inputs, and other interactive descendants retain their
 own behavior. Radios in a single-selection list should share a `name`, just as
 they would in an unenhanced native radio group.
 
+## Ordered lists
+
+Set `ordered` when item order carries meaning, such as recipe steps. Each visible item receives
+`aria-posinset` and `aria-setsize`, so assistive technology reports its position. The list
+renders no counters: numbering the content shows, if any, stays in the item text. Items that
+already carry authored positions, as in a virtualized slice, keep them.
+
+```html
+<rc-list ordered aria-label="Directions">
+  <rc-list-item>1. Heat the oven.</rc-list-item>
+  <rc-list-item>2. Mix the batter.</rc-list-item>
+</rc-list>
+```
+
+## Reordering
+
+Set `reorderable` to let people change the order. It implies `ordered`. Give each item a native
+`<button data-rc-reorder-handle>`, usually in the `trailing` slot, and label it yourself. Handles
+without an authored `aria-description` get a short keyboard hint, which `reorderMessages` can
+replace along with every announcement.
+
+- **Pointer:** press a handle and drag. The lifted item follows the pointer, the items it passes
+  shift out of its way, and the nearest scroll container scrolls near its edges. Escape cancels.
+  A press without movement stays a plain button press.
+- **Touch and pen:** as on Android, a long press anywhere on an item also picks it up, then
+  drag. Moving before the press completes scrolls the list instead, and lifting the finger
+  after the drag does not also activate a control in the item. A mouse drags only by the
+  handle. Item text cannot be selected in a `reorderable` list.
+- **Keyboard:** Space or Enter picks the item up. The block-axis arrow keys, Home, and End move
+  it, Space or Enter drops it, and Escape returns it to where it started. Moving focus away
+  drops it. Each step is announced through a polite live region in the nearest open dialog or
+  popover, else the document body.
+
+Each committed move fires a cancelable `rc-list-reorder` event with `{ item, from, to }`. Left
+alone, the list moves the item's node itself, so plain HTML needs no script. A framework that
+renders the items cancels the event and reorders its own data; focus returns to the moved
+item's handle even when the framework replaces the item's nodes. A pointer drag fires once on
+drop. The keyboard fires on every step, and once more when a reorder is canceled.
+
+```html
+<rc-list reorderable aria-label="Photo order">
+  <rc-list-item>
+    Cover photo
+    <button slot="trailing" type="button" data-rc-reorder-handle aria-label="Reorder cover photo">
+      ⠿
+    </button>
+  </rc-list-item>
+  <rc-list-item>
+    Plated
+    <button slot="trailing" type="button" data-rc-reorder-handle aria-label="Reorder plated">
+      ⠿
+    </button>
+  </rc-list-item>
+</rc-list>
+```
+
+```js
+list.addEventListener('rc-list-reorder', (event) => {
+  event.preventDefault();
+  photos = move(photos, event.detail.from, event.detail.to);
+});
+```
+
+While an item is lifted it carries `data-dragging` and the list carries `data-reordering`. Themes
+style the lifted item with the `--rc-list-item-dragged-*` properties and animate the shifting
+items with `--rc-list-item-reorder-duration`. Reduced motion turns that shift off.
+
+### Localizing the reorder text
+
+The handle hint and announcements follow the list's own `lang`, else `<html lang>`. Override
+them per list with `reorderMessages`, or for every list with `registerMessages()` from
+`@rcarls/rc-common` under `reorder` (`instructions`, `grabbed`, `moved`, `dropped`,
+`canceled`).
+
+## Expandable details
+
+An item can carry a supporting region below its row in the `details` slot. Mark a button inside
+the item, usually in the `trailing` slot, with `data-rc-list-item-toggle`. The item wires the
+button's `aria-expanded` and `aria-controls`, keeps the region `hidden` while collapsed, and
+fires `rc-list-item-toggle` with the requested state. Use `default-expanded` for an initial
+uncontrolled state, or set `expanded` to control it; assign `undefined` to release control.
+
+```html
+<rc-list aria-label="Ingredients">
+  <rc-list-item>
+    3 garlic cloves, chopped
+    <button slot="trailing" type="button" data-rc-list-item-toggle aria-label="Garlic details">
+      i
+    </button>
+    <div slot="details">"garlic" is not a recognized unit of measure.</div>
+  </rc-list-item>
+</rc-list>
+```
+
+The region spans the text and trailing columns, so its content wraps freely even while the row
+text truncates.
+
 ## Action targets
 
 For a row whose primary action is not its selection input, set `interactive`
@@ -82,5 +179,10 @@ collapse the shared trailing track and place trailing metadata below content:
 }
 ```
 
+To render only part of a long list, wrap it in `rc-virtual-scroller` and give
+each rendered row `aria-posinset` and `aria-setsize` for its place in the whole set. The list
+then gives first- and last-row styling only to the set's real first and last
+rows, not to the ends of the rendered slice.
+
 Import `@rcarls/rc-list` to use the classes without registering them, or import
 `@rcarls/rc-list/define` to register `<rc-list>` and `<rc-list-item>`.