react-native-roster 0.0.0 → 0.1.0

package/NOTICE.md

@@ -0,0 +1,29 @@
+# Notices and attributions
+
+react-native-roster uses the MIT license; see [LICENSE](./LICENSE).
+
+## Adapter dependencies
+
+- **rrule-temporal**, ggaabe, MIT: <https://github.com/ggaabe/rrule-temporal>.
+  Version 1.6.0 supplies the recurrence engine.
+- **@js-temporal/polyfill**, Temporal polyfill contributors, ISC:
+  <https://github.com/js-temporal/temporal-polyfill>. Version 0.5.1 supplies
+  the adapter's absolute-time conversion.
+
+These dependencies are imported only through `./rrule`; root and core consumers
+do not load them. They are installed as dependencies and are not bundled.
+
+## Rendering peer
+
+- **@legendapp/list**, Legend, MIT: <https://github.com/LegendApp/legend-list>.
+  A peer dependency, with 2.0.19 used in development; Roster uses it to virtualize lanes.
+
+## Predecessor
+
+[react-big-scheduler](https://github.com/StephenChou1017/react-big-scheduler),
+Stephen Chou, is the predecessor this package replaces for the roster read surface.
+react-native-roster is an independent implementation, not a fork; no predecessor
+source is copied into this package.
+
+Retain upstream licenses when adding third-party source or assets. Add new
+attributions here in the same change. References do not imply endorsement.

package/README.md

@@ -1,5 +1,458 @@
 # react-native-roster
 
-Layered intervals with provenance across lanes and a shared time axis for React Native.
+**Lanes, layers, and sources on one time axis.**
 
-This is a placeholder release that reserves the package name; it contains no usable code. The first usable version will be published from https://github.com/simiancraft/react-native-roster. A live demo runs at https://simiancraft.github.io/react-native-roster/.
+[![Gallery](https://img.shields.io/badge/▶%20Gallery-lanes%2C%20layers%2C%20and%20sources-4f46e5?style=for-the-badge)](https://simiancraft.github.io/react-native-roster/)
+
+[![CI](https://github.com/simiancraft/react-native-roster/actions/workflows/ci.yml/badge.svg)](https://github.com/simiancraft/react-native-roster/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/simiancraft/react-native-roster?logo=codecov)](https://codecov.io/github/simiancraft/react-native-roster)
+[![Types: included](https://img.shields.io/badge/types-included-3178c6?logo=typescript)](#contract)
+[![Core under 15 kB](https://img.shields.io/badge/core-%3C15%20kB-0f766e)](./.size-limit.json)
+[![Expo SDK 54](https://img.shields.io/badge/Expo-SDK%2054-000020?logo=expo)](./demo/package.json)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/simiancraft/react-native-roster/badge)](https://securityscorecards.dev/viewer/?uri=github.com/simiancraft/react-native-roster)
+
+A read surface for React Native and web that renders who is on, when, and why.
+Feed it absolute intervals with provenance; press any filled or removed span and
+get back the exact rules, rows, or exclusions that produced it. Daylight-saving
+transitions are drawn honestly: skipped hours are hatched, repeated hours appear
+twice. `Roster` stacks many lanes horizontally; `Schedule` opens one lane as a
+week of wall-clock columns. The core is standard JavaScript plus `Intl`, under
+15 kB, and recurrence expansion is an optional subpath.
+
+It is not a calendar, a booking system, or a drag-to-create editor; you own
+mutations and persistence. If you want an event grid with gestures, an event
+calendar library is the better fit. If you need to explain coverage across two
+hundred people without lying about time zones, this is the one.
+
+- **Provenance on every span.** Intervals and gaps carry `sources`; presses
+  return the winning span's `(kind, id)` list, including the exclusion that
+  removed time.
+- **Honest time.** Elapsed-time roster weeks are 167 or 169 hours wide across a
+  transition; schedule columns hatch skipped hours and draw repeated hours twice.
+- **Layers with roles.** `availability`, `booking`, and `custom` layers stack by
+  z-order; coverage math unions availability, subtracts bookings, and sorts.
+- **Recurrence adapter.** Weekly, daily, and monthly rules with exclusions,
+  caps, and content-keyed caches, kept out of the core.
+- **Zones everywhere.** Input-bearing regions accept component types, singletons accept nodes, and
+  every chrome region takes `style` plus a NativeWind `className` twin.
+- **Virtualized and measured.** Geometry runs only for mounted lanes; CI gates
+  layout, coverage, bundle size, and browser action budgets.
+
+## Install
+
+```sh
+bun add react-native-roster @legendapp/list
+bunx expo install react-native-reanimated --bun
+```
+
+To try an unreleased checkout instead, pack it with `bun pm pack --destination
+.cache` and `bun add` the printed tarball path. Keep React, React Native, and
+Expo aligned with your SDK; the
+tested demo uses Expo SDK 54, React 19.1, React Native 0.81.5, LegendList
+2.0.19, and Reanimated 3.19.5. Web also needs React DOM and React Native Web.
+Peer ranges are React 18.2+, React Native 0.74+, and LegendList 2+; Reanimated
+is optional for core-only use and required by `Roster`. On Metro before React
+Native 0.79, enable `resolver.unstable_enablePackageExports` so the `/core`,
+`/rrule`, and `/nativewind` subpaths resolve.
+
+## Quick start: static intervals
+
+Twenty lines, no adapter. Give the component a bounded height.
+
+```tsx
+import { Roster } from 'react-native-roster';
+import type { Lane } from 'react-native-roster/core';
+
+const lanes: Lane[] = [{
+  id: 'one', label: 'Lane one', layers: [{
+    id: 'open', role: 'availability', z: 0,
+    style: { color: '#4f9478' },
+    intervals: [{
+      start: Date.UTC(2024, 0, 1, 9), end: Date.UTC(2024, 0, 1, 17),
+      sources: [{ kind: 'table', id: 'row-one' }],
+    }],
+  }],
+}];
+
+export function Example() {
+  return <Roster lanes={lanes}
+    style={{ height: 480, flex: undefined }}
+    windowSpec={{ span: 'week', anchorDate: '2024-01-01', timezone: 'UTC' }}
+    onIntervalPress={(rect, lane) => console.log(lane.id, rect.sources)} />;
+}
+```
+
+Press the interval to receive its `table / row-one` source. `minuteStep`
+defaults to 60 and accepts any positive divisor of 60; it changes ticks and
+empty-space snapping, never interval boundaries. `rowHeight` defaults to 48 and
+`pxPerMinute` to a minimum of 0.5, growing to fit wider viewports.
+
+## Quick start: recurring local hours
+
+```tsx
+import { Roster } from 'react-native-roster';
+import type { Lane, WindowSpec } from 'react-native-roster/core';
+import { windowFor } from 'react-native-roster/core';
+import { expandRuleSet } from 'react-native-roster/rrule';
+import type { RuleSet } from 'react-native-roster/rrule';
+
+const spec: WindowSpec = {
+  span: 'week', anchorDate: '2024-01-01', timezone: 'America/Chicago',
+};
+const set: RuleSet = {
+  rules: [{
+    id: 'weekday-hours', kind: 'include', frequency: 'WEEKLY',
+    dtstart: '2024-01-01', byweekday: [0, 1, 2, 3, 4],
+    hourstart: 9, hourend: 17, timezone: 'America/Chicago',
+  }],
+  dates: [{
+    id: 'closed', kind: 'exclude', date: '2024-01-02',
+    timezone: 'America/Chicago', note: 'Closed all day',
+  }],
+};
+const result = expandRuleSet(set, windowFor(spec));
+const lane: Lane = {
+  id: 'one', label: 'Lane one', timezone: 'America/Chicago',
+  complete: result.complete,
+  layers: [{
+    id: 'open', role: 'availability', z: 0, style: { color: '#4f9478' },
+    intervals: result.intervals, gaps: result.gaps,
+  }],
+};
+
+export function RecurringExample() {
+  return <Roster lanes={[lane]} windowSpec={spec}
+    style={{ height: 480, flex: undefined }}
+    onGapPress={(rect) => console.log(rect.sources)} />;
+}
+```
+
+Tuesday is a gap carrying the dated exclusion; the other weekdays carry the
+include rule. Expand once per `windowFor(spec)` in your screen's hook, never
+inside a slot component; content-keyed caches reuse unchanged occurrences. The
+[adapter guide](./docs/adapters.md) covers validation, caps, cache lifetime,
+and mapping tables or feeds without a recurrence dependency;
+[recurrence semantics](./docs/recurrence.md) records the exact anchor, UNTIL,
+COUNT, and BYSETPOS rules.
+
+## Contract
+
+| Term | Meaning |
+| --- | --- |
+| roster | Shared time axis, lanes, and layers. |
+| lane | One person or resource row; `id`, `label`, `layers`, and optional display metadata. |
+| layer | Ordered intervals and gaps with `id`, `role`, `z`, and `style`. |
+| interval | Covered `[start, end)` in epoch milliseconds, with `sources: Source[]`. |
+| gap | Removed `[start, end)` with exclusion sources; survives complete subtraction. |
+| source | `{ kind, id, label? }`; identity is `(kind, id)`, never the label. |
+| window | Absolute `{ start, end }` only; span and resolution belong to the axis. |
+| projection | Horizontal elapsed time, or day columns with wall-clock hours. |
+| adapter | Consumer-side conversion from upstream data to lanes and layers. |
+| schedule | One lane projected into days across and hours down. |
+
+`LayerRole` is `'availability' | 'booking' | 'custom'`. The first two feed
+coverage math (`availabilityMinutes`, `bookingMinutes`, and
+`availabilityMinusBookingMinutes`); use `custom` for anything else. `LayerStyle`
+is `{ color, highlightColor?, inset?, opacity? }`; the engine applies inset on
+the cross axis and returns final bounds for drawing and hit testing.
+
+`Lane` also accepts optional data-quality fields: `version` (bump when layers
+change), `timezone` (a badge), `flag: 'never-set'` for lanes you know were never
+configured, `complete: false` when an adapter cap truncated the result, and
+`meta` for your own display data. The notices default to "No availability set"
+and "Availability may be incomplete"; both are localizable props.
+
+## Entry points
+
+| Import | Shipped surface |
+| --- | --- |
+| `react-native-roster` | `Roster`, `Schedule`, `useRoster`, `useSchedule`, slot components, and all core exports. |
+| `react-native-roster/core` | Types, `layoutLane`, `coverageFor`, `flagFor`, axis helpers, comparators, and counters. Standard JavaScript and `Intl` only. |
+| `react-native-roster/rrule` | `expandRuleSet`, `envelopeFor`, types, and expansion counters and caches. Uses pinned `rrule-temporal` and `@js-temporal/polyfill`. |
+| `react-native-roster/nativewind` | Registers `Roster` and `Schedule` with NativeWind so their `className` props resolve; re-exports the registered components. |
+
+Root and core never import recurrence dependencies. Metro selects TypeScript
+source through the `react-native` export condition; other bundlers select
+emitted CommonJS with declarations in `dist/src`. The emit is CommonJS, so
+importing one function from the root costs the whole root bundle; import from
+`/core` for a core-only bundle. Cache keys, counters, and clearing are in
+[caches](./docs/caches.md).
+
+## Navigation and interaction
+
+A `WindowSpec` is `{ span: 'day' | 'week' | 'month', anchorDate, timezone, wkst? }`
+or `{ span: 'custom', window, timezone }`. `anchorDate` is a local `YYYY-MM-DD`.
+`windowFor`, `prev`, `next`, and `today` handle bounds and navigation; weeks
+start Monday (weekday 0) unless `wkst` says otherwise. Components accept
+`onNavigate` but ship no toolbar; your controls update the controlled spec.
+
+Three zones take part in a render: the rule timezone interprets local hours in
+the adapter, the lane timezone is a badge, and `windowSpec.timezone` drives the
+projection. Changing the view zone preserves the local anchor and usually reuses
+expanded occurrences. Column spans, rollbacks across midnight, and pointer
+inversion are documented in [timezones](./docs/timezones.md).
+
+Presses resolve one result: intervals before gaps, highest z first, later
+layers winning equal-z ties. `onIntervalPress(rect, lane)` and
+`onGapPress(rect, lane)` return the contributing sources; `onCellPress(lane,
+time)` returns snapped absolute time for empty space. `onIntervalHover` is
+Roster's web-only pointer callback. `highlightSource={{ kind, id }}` applies
+`highlightColor` to every matching rect without new geometry. Sorting defaults
+to `byLabel`; `byCoverage({ measure })` sorts by coverage descending.
+
+## Roster zones
+
+Props ending in `Component` accept `ComponentType<Input>` and are mounted by React.
+Props ending in `Zone` accept `ReactNode`. Define components at module scope so
+state survives rerenders; hooks and class components are supported. Compose the
+exported default components inside replacements to retain scrolling, geometry,
+or press behavior. Pass `null` to a node slot to suppress its default.
+
+| Slot | Component inputs or node | Default and behavior |
+| --- | --- | --- |
+| `emptyZone` | `ReactNode` | `RosterEmpty`: No lanes. |
+| `cornerZone` | `ReactNode` | `RosterCorner`: nothing; the cell above the labels, `laneLabelWidth` wide. |
+| `laneLabelComponent` | `lane`, `flag`, `complete`, `viewTimezone`, localized labels | `RosterLaneLabel`: label, differing IANA zone badge, and notices. |
+| `headerCellComponent` | `HeaderCellInput` (`tick`) | `RosterHeaderCell`: tick label. |
+| `intervalComponent` | `rect`, `layer`, `lane`, `highlighted` | `RosterInterval`: positioned colored rect, with final inset bounds. |
+| `gapComponent` | `rect`, `layer`, `lane` | `RosterGap`: no visible content; the row supplies pressable bounds. |
+| `gridComponent` | `ticks`, `contentWidth` | `RosterGrid`: one hairline per tick behind every lane. |
+| `headerComponent` | `ticks`, `projection`, `scroll`, `contentWidth`, `headerCellComponent` | `RosterHeader`: frozen header following horizontal offset. |
+| `laneLabelColumnComponent` | `labels`, `projection`, `scroll`, `laneLabelComponent` | `RosterLaneLabelColumn`: frozen labels following vertical offset. |
+| `bodyComponent` | Ordered `lanes`, `window`, `geometryFor`, `projection`, `scroll`, `press`, `ticks`, `viewport`, `contentWidth`, highlight and hover, incomplete label, and rect components | `RosterBody`: virtualized lanes. |
+
+`RosterBody` composes `RosterBodyLayout`, which arranges `gridZone` and `listZone`
+nodes with scroll wiring, and `RosterLaneList`, which owns LegendList and its
+per-lane callback. The body waits for viewport measurement before mounting the list.
+
+```tsx
+import type { LaneLabelInput } from 'react-native-roster';
+import { Text } from 'react-native';
+
+function LaneLabel({ lane }: LaneLabelInput) {
+  return <Text>{lane.label}</Text>;
+}
+
+<Roster lanes={lanes} windowSpec={windowSpec}
+  laneLabelComponent={LaneLabel} cornerZone={<Text>People</Text>} />
+```
+
+A custom interval component positions at `rect.x/y`, uses `rect.width/height/z`,
+and sets `pointerEvents="none"` so the parent hit-test walk owns presses. Gap
+fillers are already inside positioned pressables. `useRoster` exposes ordered
+lanes, coverage, lane state, ticks, `geometryFor`, shared scrolling, `press`,
+viewport measurement, navigation, and status for fully custom layouts.
+
+Chrome regions take style props: `style`, `headerStyle` (the 40 px header row
+holding the corner and ticks), `laneLabelColumnStyle`, and `bodyStyle`.
+`laneLabelWidth` sizes the corner and label column, default 180. Each style
+prop has a `className` twin; see [NativeWind](#nativewind).
+
+### Consumer data in slot components
+
+For consumer data beyond a slot's Input, mount a React context provider above
+`Roster` and read it with `useContext` in a module-scope slot component. This
+example supplies density and locale while keeping the header cell type stable:
+
+```tsx
+import { createContext, useContext } from 'react';
+import { Text } from 'react-native';
+import type { HeaderCellInput, RosterProps } from 'react-native-roster';
+import { Roster } from 'react-native-roster';
+
+type SlotPreferences = {
+  density: 'compact' | 'comfortable';
+  locale: string;
+};
+
+const SlotPreferencesContext = createContext<SlotPreferences>({
+  density: 'comfortable',
+  locale: 'en-US',
+});
+
+function LocalizedHeaderCell({ tick }: HeaderCellInput) {
+  const { density, locale } = useContext(SlotPreferencesContext);
+  const label = new Intl.DateTimeFormat(locale, {
+    timeZone: 'UTC',
+    ...(tick.kind === 'day'
+      ? { month: 'short', day: 'numeric' }
+      : { hour: 'numeric', minute: '2-digit' }),
+  }).format(tick.time);
+
+  return (
+    <Text numberOfLines={1} style={{ padding: density === 'compact' ? 2 : 6 }}>
+      {label}
+    </Text>
+  );
+}
+
+export function ConsumerRoster({ lanes }: Pick<RosterProps, 'lanes'>) {
+  return (
+    <SlotPreferencesContext.Provider value={{ density: 'compact', locale: 'en-GB' }}>
+      <Roster
+        lanes={lanes}
+        windowSpec={{ span: 'week', anchorDate: '2024-01-01', timezone: 'UTC' }}
+        style={{ height: 480, flex: undefined }}
+        headerCellComponent={LocalizedHeaderCell}
+      />
+    </SlotPreferencesContext.Provider>
+  );
+}
+```
+
+An inline closure or a memoized factory that returns a new component per render
+is not the recommended path. A new interval component type remounts every interval
+and defeats the body's content key. Context supplies changing consumer data while
+preserving the module-scope component type.
+
+## Schedule and its zones
+
+```tsx
+import { Schedule } from 'react-native-roster';
+import type { Lane } from 'react-native-roster/core';
+
+export function Week({ lane }: { lane: Lane }) {
+  return <Schedule lane={lane} minuteStep={60}
+    style={{ height: 600, flex: undefined }}
+    windowSpec={{ span: 'week', anchorDate: '2024-01-01', timezone: 'UTC' }}
+    onIntervalPress={(rect) => console.log(rect.sources)} />;
+}
+```
+
+Only day and week specs are accepted. The component measures its width,
+reserves a 48 px gutter, and fits the day columns without horizontal scrolling.
+`pxPerHour` defaults to 48. Chrome takes `style`, `headerStyle`, `gutterStyle`,
+and `daysStyle`, each with a `className` twin.
+
+| Slot | Component inputs or node | Default and behavior |
+| --- | --- | --- |
+| `gutterComponent` | `hours`, `pxPerHour` | `ScheduleGutter`: 24 frozen hour labels. |
+| `gridComponent` | `hours`, `pxPerHour` | `ScheduleGrid`: 24 bordered hour bands behind each day's rects. |
+| `dayHeaderComponent` | `day` | `ScheduleDayHeader`: weekday, localDate, and transition badge. |
+| `skippedDateComponent` | `localDate` | `ScheduleSkippedDate`: zero-width header marker for a wholly skipped date. |
+| `columnComponent` | `day`, `rects`, `gapRects`, `lane`, `highlightSource`, `press`, interval and gap components | `ScheduleColumn`: final rect bounds in layer order. |
+| `transitionComponent` | `day`, `transition`, `y`, `dividerY`, `height`, `width` | `ScheduleTransition`: skipped-time hatch, or repeat divider and again label. |
+| `nowLineComponent` | `y`, `column` | `ScheduleNowLine`: line in the current day's column, updated each minute. |
+| `intervalComponent`, `gapComponent` | Same inputs as Roster | Shared `RosterInterval` and `RosterGap`. |
+| `incompleteComponent` | `lane`, `label` | `ScheduleIncomplete`: notice above the grid when the lane is incomplete. |
+
+## NativeWind
+
+`className` is a first-class prop on `Roster` and `Schedule`, alongside `style`.
+Every chrome style prop has a class twin: `className`, `headerClassName`,
+`laneLabelColumnClassName`, and `bodyClassName` on Roster; `className`,
+`headerClassName`, `gutterClassName`, and `daysClassName` on Schedule. A class
+on a region replaces that region's default paint (background and border colors)
+while its structure (size, flex, overflow) stays. This is deliberate: React
+Native Web renders object styles inline, and inline paint would otherwise beat
+any class.
+
+Set up NativeWind 4 as usual (the demo's [babel.config.js](./demo/babel.config.js),
+[metro.config.js](./demo/metro.config.js), [tailwind.config.js](./demo/tailwind.config.js),
+and [global.css](./demo/global.css) are a working reference), add the optional
+peer with `bun add nativewind`, and register the components once at your app
+root:
+
+```tsx
+// app/_layout.tsx
+import '../global.css';
+import 'react-native-roster/nativewind';
+```
+
+```tsx
+import { Roster } from 'react-native-roster';
+
+<Roster
+  lanes={lanes}
+  windowSpec={windowSpec}
+  className="flex-1 rounded-xl bg-background"
+  headerClassName="border-b border-border bg-card"
+  laneLabelColumnClassName="border-r border-border bg-card"
+  laneLabelWidth={220}
+/>
+```
+
+Slot components are ordinary React Native views, so a custom `laneLabelComponent` or
+`intervalComponent` uses `className` on `View` and `Text` directly. Without the
+entry point, class props are ignored and style props still work. The entry
+point is the package's only module with side effects and is listed in
+`sideEffects`. The [showcase route](./demo/app/showcase.tsx) styles every region
+and zone this way in light and dark palettes.
+
+## Gallery and platform support
+
+The [Expo gallery](https://simiancraft.github.io/react-native-roster/) is the
+demo; there is no Storybook. Run it locally with `bun install --frozen-lockfile`,
+`bun run build`, and `bun run demo:web` (add `EXPO_OFFLINE=1` in a restricted
+network). The home page lists every fixture route:
+
+- Empty, one, 20, and 200 lanes; inset layers; default and replaced zones.
+- Day, week, and month routes at 15, 30, and 60-minute steps.
+- Full-day gaps, lane flags, equal-z precedence, highlight, coverage sorting,
+  and incomplete expansion.
+- Chicago DST weeks, mixed rule, lane, and view zones, and editable adapter routes.
+- Schedule empty, layered, excluded, spring, fall, Lord Howe, Apia, incomplete,
+  midnight, side-by-side projections, and every zone.
+- The showcase at `/showcase`: twelve generated people across seven zones,
+  weekly hours and exclusions from the recurrence adapter, booked events, day
+  and week spans, sorting, filtering, and a per-person Schedule, styled with
+  NativeWind class props and slot components, with a sun and moon theme toggle.
+  Names, titles, and the organization come from `@faker-js/faker` with a fixed
+  seed; any resemblance to real people is coincidental.
+
+| Platform | Support and evidence |
+| --- | --- |
+| Web via React Native Web | Static export and Chromium gallery checks; first-class target. |
+| iOS | React Native implementation; device rendering and Hermes behavior not yet verified here. |
+| Android | React Native implementation; device rendering and release performance not yet captured. |
+| Node and Bun | Built core and adapter work without a renderer; root components require native peers or a web bundler. |
+
+## Performance
+
+Workload W is 200 lanes, one week, two layers, a 24-lane viewport, and
+15-minute ticks: 63 interval rects and 7 gap rects per lane. The
+[committed CI baseline](./test/performance/baseline.json) on GitHub Actions
+ubuntu-latest records target-cold layout of 24 lanes at 2.070 ms and coverage of
+all 200 lanes at 1.063 ms, gated below 16 ms everywhere and within 1.5 times the
+baseline in CI. Size gates hold core under 15 kB and root under 44 kB. Device
+captures and the paired comparison against other libraries are described, not
+yet recorded, in the [performance guide](./docs/performance.md); CI timings are
+not phone frame rates.
+
+## What this isn't
+
+This is a read surface. Consumers own creation, dragging, resizing,
+persistence, and permission checks through their own interactions. It is not a
+month grid or an arbitrary event list, and it does not expand rules inside the
+core. The short [design note](./docs/design.md) explains the reasoning.
+
+## Development and reference
+
+```sh
+bunx playwright install chromium
+bun run check
+```
+
+`check` runs Biome, library, test, and demo typechecks, React Compiler safety,
+the library build, the static web export, tests with coverage, knip, strict
+publint, size-limit, and Playwright.
+
+- [Migrations](https://github.com/simiancraft/react-native-roster/blob/main/docs/migrations.md) lists prop renames by version with before-and-after examples.
+- [Adapter guide](./docs/adapters.md), [recurrence semantics](./docs/recurrence.md),
+  [timezones](./docs/timezones.md), [caches](./docs/caches.md), and the
+  [performance guide](./docs/performance.md).
+- [Design note](./docs/design.md): precompute, then render geometry.
+- Area landing pages: [core](./src/core/README.md), [Roster](./src/components/roster/README.md),
+  [Schedule](./src/components/schedule/README.md), [layers](./src/components/layers/README.md),
+  [primitives](./src/components/primitives/README.md), [rrule adapter](./src/adapters/rrule/README.md),
+  [nativewind](./src/nativewind/README.md), the [gallery](./demo/components/gallery/README.md), and the
+  [showcase](./demo/components/team-roster/README.md), and the [theme](./demo/components/theme/README.md);
+  [adding an adapter](./docs/adding-an-adapter.md)
+  is the contributor recipe.
+- [llms.txt](./llms.txt): integration instructions for agents.
+- [CONTRIBUTING.md](./CONTRIBUTING.md) and [AGENTS.md](./AGENTS.md): contributor workflow.
+- [CHANGELOG.md](./CHANGELOG.md): release history, maintained by semantic-release.
+- [SECURITY.md](./SECURITY.md), [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md), and [NOTICE.md](./NOTICE.md).
+
+MIT, copyright 2026 Jesse Harlin (the-simian). See [LICENSE](./LICENSE).

package/dist/src/adapters/rrule/cache.d.ts

@@ -0,0 +1,15 @@
+import type { Window } from '../../core';
+import type { ExpandStats } from './types';
+export type Occurrences = {
+    spans: Window[];
+    capped: boolean;
+};
+export declare const occurrences: Map<string, Occurrences>;
+export declare function touch<T>(cache: Map<string, T>, key: string, value: T): T;
+export declare function trim<T>(cache: Map<string, T>, limit: number): void;
+export declare function retainedEnvelope(window: Window, limit: number): Window;
+export declare function recordStats(stats: ExpandStats): void;
+export declare function expandStats(): ExpandStats;
+export declare function resetExpandStats(): void;
+export declare function clearExpandCache(): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/src/adapters/rrule/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../../src/adapters/rrule/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,MAAM,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAC/D,eAAO,MAAM,WAAW,0BAAiC,CAAC;AAM1D,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAIxE;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAElE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAWtE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAEpD;AAED,wBAAgB,WAAW,IAAI,WAAW,CAEzC;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}

package/dist/src/adapters/rrule/cache.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.occurrences = void 0;
+exports.touch = touch;
+exports.trim = trim;
+exports.retainedEnvelope = retainedEnvelope;
+exports.recordStats = recordStats;
+exports.expandStats = expandStats;
+exports.resetExpandStats = resetExpandStats;
+exports.clearExpandCache = clearExpandCache;
+const envelope_1 = require("./envelope");
+exports.occurrences = new Map();
+const envelopes = new Map();
+const counts = { rules: 0, dates: 0, expanded: 0, cacheHits: 0, cacheMisses: 0 };
+// Map insertion order is the LRU: reads move entries to the newest end.
+// Envelope retention selects bounds only; no netted result is retained.
+function touch(cache, key, value) {
+    cache.delete(key);
+    cache.set(key, value);
+    return value;
+}
+function trim(cache, limit) {
+    while (cache.size > limit)
+        cache.delete(cache.keys().next().value);
+}
+function retainedEnvelope(window, limit) {
+    trim(envelopes, limit);
+    for (const [id, envelope] of [...envelopes].reverse()) {
+        if (envelope.start <= window.start && envelope.end >= window.end) {
+            return touch(envelopes, id, envelope);
+        }
+    }
+    const envelope = (0, envelope_1.envelopeFor)(window);
+    touch(envelopes, JSON.stringify(envelope), envelope);
+    trim(envelopes, limit);
+    return envelope;
+}
+function recordStats(stats) {
+    for (const key of Object.keys(counts))
+        counts[key] += stats[key];
+}
+function expandStats() {
+    return { ...counts };
+}
+function resetExpandStats() {
+    for (const key of Object.keys(counts))
+        counts[key] = 0;
+}
+function clearExpandCache() {
+    exports.occurrences.clear();
+    envelopes.clear();
+}
+//# sourceMappingURL=cache.js.map

package/dist/src/adapters/rrule/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../../src/adapters/rrule/cache.ts"],"names":[],"mappings":";;;;;;;;;;AACA,yCAAyC;AAI5B,QAAA,WAAW,GAAG,IAAI,GAAG,EAAuB,CAAC;AAC1D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;AAC5C,MAAM,MAAM,GAAgB,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAE9F,wEAAwE;AACxE,wEAAwE;AACxE,eAAyB,KAAqB,EAAE,GAAW,EAAE,KAAQ;IACnE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,cAAwB,KAAqB,EAAE,KAAa;IAC1D,OAAO,KAAK,CAAC,IAAI,GAAG,KAAK;QAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAe,CAAC,CAAC;AAC/E,CAAC;AAED,0BAAiC,MAAc,EAAE,KAAa;IAC5D,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACvB,KAAK,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QACtD,IAAI,QAAQ,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,IAAI,QAAQ,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC;YACjE,OAAO,KAAK,CAAC,SAAS,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,IAAA,sBAAW,EAAC,MAAM,CAAC,CAAC;IACrC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;IACrD,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACvB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,qBAA4B,KAAkB;IAC5C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAA6B;QAAE,MAAM,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;AAC/F,CAAC;AAED;IACE,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;AACvB,CAAC;AAED;IACE,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAA6B;QAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACrF,CAAC;AAED;IACE,QAAA,WAAW,CAAC,KAAK,EAAE,CAAC;IACpB,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC"}

package/dist/src/adapters/rrule/envelope.d.ts

@@ -0,0 +1,3 @@
+import type { Window } from '../../core';
+export declare function envelopeFor(window: Window): Window;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/src/adapters/rrule/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../../src/adapters/rrule/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAIzC,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/src/adapters/rrule/envelope.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envelopeFor = envelopeFor;
+// Absolute 48-hour padding exceeds the 26-hour difference between view zones.
+// Includes, excludes, and dates share these bounds before subtraction.
+function envelopeFor(window) {
+    return { start: window.start - 48 * 3_600_000, end: window.end + 48 * 3_600_000 };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/src/adapters/rrule/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../../src/adapters/rrule/envelope.ts"],"names":[],"mappings":";;;AAEA,8EAA8E;AAC9E,uEAAuE;AACvE,qBAA4B,MAAc;IACxC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,GAAG,EAAE,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,GAAG,EAAE,GAAG,SAAS,EAAE,CAAC;AACpF,CAAC"}

package/dist/src/adapters/rrule/expand.d.ts

@@ -0,0 +1,4 @@
+import type { Window } from '../../core';
+import type { ExpandOptions, ExpandResult, RuleSet } from './types';
+export declare function expandRuleSet(set: RuleSet, window: Window, options?: ExpandOptions): ExpandResult;
+//# sourceMappingURL=expand.d.ts.map

package/dist/src/adapters/rrule/expand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand.d.ts","sourceRoot":"","sources":["../../../../src/adapters/rrule/expand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,MAAM,EAAE,MAAM,YAAY,CAAC;AAM3D,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EAIZ,OAAO,EACR,MAAM,SAAS,CAAC;AAGjB,wBAAgB,aAAa,CAC3B,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,aAAkB,GAC1B,YAAY,CAgFd"}