react-native-roster 0.0.0 → 0.1.0

package/package.json

@@ -1,19 +1,166 @@
 {
   "name": "react-native-roster",
-  "version": "0.0.0",
-  "description": "Layered intervals with provenance across lanes and a shared time axis for React Native. Placeholder release; the API is unreleased.",
-  "license": "MIT",
+  "version": "0.1.0",
+  "description": "Layered intervals with provenance across lanes and a shared time axis for React Native.",
+  "keywords": [
+    "react-native",
+    "expo",
+    "roster",
+    "lanes",
+    "intervals",
+    "provenance",
+    "nativewind"
+  ],
   "author": "Jesse Harlin (the-simian) <info@simiancraft.com>",
+  "license": "MIT",
+  "homepage": "https://simiancraft.github.io/react-native-roster/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/simiancraft/react-native-roster.git"
   },
-  "homepage": "https://simiancraft.github.io/react-native-roster/",
   "bugs": {
     "url": "https://github.com/simiancraft/react-native-roster/issues"
   },
-  "keywords": ["react-native", "expo", "roster", "schedule", "timeline", "availability", "nativewind"],
-  "main": "index.js",
-  "files": ["index.js", "README.md", "LICENSE"],
-  "publishConfig": { "access": "public" }
+  "type": "commonjs",
+  "sideEffects": [
+    "./src/nativewind/index.ts",
+    "./dist/src/nativewind/index.js"
+  ],
+  "main": "./src/index.ts",
+  "react-native": "./src/index.ts",
+  "types": "./dist/src/index.d.ts",
+  "browser": {
+    "./dist/src/components/primitives/press-point.js": "./dist/src/components/primitives/press-point.web.js",
+    "./dist/src/components/roster/lanes/interval-hover.js": "./dist/src/components/roster/lanes/interval-hover.web.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "bun": "./src/index.ts",
+      "react-native": "./src/index.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./core": {
+      "types": "./dist/src/core/index.d.ts",
+      "bun": "./src/core/index.ts",
+      "react-native": "./src/core/index.ts",
+      "default": "./dist/src/core/index.js"
+    },
+    "./rrule": {
+      "types": "./dist/src/adapters/rrule/index.d.ts",
+      "bun": "./src/adapters/rrule/index.ts",
+      "react-native": "./src/adapters/rrule/index.ts",
+      "default": "./dist/src/adapters/rrule/index.js"
+    },
+    "./nativewind": {
+      "types": "./dist/src/nativewind/index.d.ts",
+      "bun": "./src/nativewind/index.ts",
+      "react-native": "./src/nativewind/index.ts",
+      "default": "./dist/src/nativewind/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md",
+    "llms.txt",
+    "docs/migrations.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "bun run clean && tsgo -p tsconfig.build.json",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write .",
+    "typecheck": "tsgo --noEmit",
+    "typecheck:test": "tsgo --noEmit -p tsconfig.test.json",
+    "check:react-compiler": "eslint 'src/components/**/*.{ts,tsx}' 'demo/components/**/*.{ts,tsx}' 'demo/app/**/*.tsx' --no-error-on-unmatched-pattern",
+    "check:knip": "knip",
+    "check:package": "publint --strict",
+    "test": "bun test --coverage",
+    "check": "bun run lint && bun run typecheck && bun run typecheck:test && bun run typecheck:demo && bun run check:react-compiler && bun run build:web && bun run test && bun run check:knip && bun run check:package && bun run check:size && bun run check:web",
+    "prepare": "if command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
+    "prepack": "bun run build",
+    "typecheck:demo": "tsgo --noEmit -p demo/tsconfig.json",
+    "build:web": "bun run build && cd demo && bunx expo export -p web",
+    "demo": "cd demo && bun run start",
+    "demo:ios": "cd demo && bun run ios",
+    "demo:android": "cd demo && bun run android",
+    "demo:web": "cd demo && bun run web",
+    "check:size": "size-limit",
+    "build:web:dev": "cd demo && bunx expo export -p web --dev --output-dir .cache/dev-dist",
+    "check:web": "bun run build:web:dev && bun scripts/check-web-performance.ts",
+    "bench:update": "bun scripts/update-performance-baseline.ts"
+  },
+  "peerDependencies": {
+    "@legendapp/list": ">=2.0.0",
+    "expo": ">=51.0.0",
+    "nativewind": ">=4.1.0",
+    "react": ">=18.2.0",
+    "react-native": ">=0.74.0",
+    "react-native-reanimated": ">=3.19.0"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    },
+    "nativewind": {
+      "optional": true
+    },
+    "react-native-reanimated": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@js-temporal/polyfill": "0.5.1",
+    "rrule-temporal": "1.6.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.12",
+    "@legendapp/list": "2.0.19",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/commit-analyzer": "13.0.1",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/github": "12.0.9",
+    "@semantic-release/npm": "13.1.5",
+    "@semantic-release/release-notes-generator": "14.1.1",
+    "@size-limit/preset-small-lib": "^13.0.3",
+    "@types/bun": "^1.3.12",
+    "@types/react": "~19.1.10",
+    "@types/react-test-renderer": "^19.1.0",
+    "@types/semver": "^7.7.0",
+    "@typescript-eslint/parser": "^8.60.1",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "eslint": "^10.4.1",
+    "eslint-plugin-react-compiler": "^19.1.0-rc.2",
+    "expo": "~54.0.37",
+    "knip": "^6.5.0",
+    "lefthook": "^2.1.9",
+    "nativewind": "4.1.x",
+    "playwright": "^1.63.0",
+    "publint": "^0.3.18",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-reanimated": "~3.19.5",
+    "react-test-renderer": "19.1.0",
+    "semantic-release": "^25.0.3",
+    "semver": "^7.7.0",
+    "size-limit": "^13.0.3",
+    "temporal-spec": "1.0.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "bun@1.4.2",
+  "workspaces": [
+    "demo"
+  ]
 }

package/src/adapters/rrule/README.md

@@ -0,0 +1,41 @@
+# rrule adapter
+
+The shipped adapter. It converts a `RuleSet` of RFC 5545 rules and dated
+overrides into absolute intervals and gaps for one window, with exact
+provenance per span.
+
+- Public subpath: `react-native-roster/rrule`
+- Exports: `expandRuleSet`, `envelopeFor`, `clearExpandCache`, `expandStats`,
+  `resetExpandStats`, and the `RosterRule`, `RosterDate`, `RuleSet`,
+  `ExpandOptions`, `ExpandResult`, and `ExpandStats` types
+- Imports: `../../core` only; never components or another adapter
+- Owns: `rrule-temporal` and the Temporal polyfill; root and core never load them
+
+## Supported input
+
+`RosterRule` covers DAILY, WEEKLY, and MONTHLY with `interval`, `count`,
+`until`, `wkst`, `byweekday`, `bymonth`, `bymonthday`, and `bysetpos`, plus
+`hourstart`, `hourend`, and an IANA `timezone`. `RosterDate` is a single local
+date, whole day or with hours. Both are `include` or `exclude`. YEARLY and
+unbounded strings are rejected by validation.
+
+## File map
+
+| File | Role |
+| --- | --- |
+| `index.ts` | the entry point; the only barrel |
+| `types.ts` | input and result types |
+| `validate.ts` | input rejection before any engine work |
+| `envelope.ts` | widens a window to whole local days per rule zone |
+| `occurrences.ts` | drives the engine and applies every calendar correction |
+| `net.ts` | nets includes against excludes into intervals and gaps |
+| `cache.ts`, `hash.ts` | retained occurrences and envelopes keyed by content |
+| `expand.ts` | the orchestrator: validate, envelope, expand, cap, net, attach |
+
+## Reference
+
+- [Recurrence semantics](../../../docs/recurrence.md): the rules `occurrences.ts` follows
+- [Caches](../../../docs/caches.md): retention, keys, and counters
+- [Adapters guide](../../../docs/adapters.md): the consumer view for any upstream shape
+- [Adding an adapter](../../../docs/adding-an-adapter.md): the contributor recipe
+- Tests: `test/adapters/rrule`

package/src/adapters/rrule/cache.ts

@@ -0,0 +1,50 @@
+import type { Window } from '../../core';
+import { envelopeFor } from './envelope';
+import type { ExpandStats } from './types';
+
+export type Occurrences = { spans: Window[]; capped: boolean };
+export const occurrences = new Map<string, Occurrences>();
+const envelopes = new Map<string, Window>();
+const counts: ExpandStats = { 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.
+export function touch<T>(cache: Map<string, T>, key: string, value: T): T {
+  cache.delete(key);
+  cache.set(key, value);
+  return value;
+}
+
+export function trim<T>(cache: Map<string, T>, limit: number): void {
+  while (cache.size > limit) cache.delete(cache.keys().next().value as string);
+}
+
+export function retainedEnvelope(window: Window, limit: number): Window {
+  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 = envelopeFor(window);
+  touch(envelopes, JSON.stringify(envelope), envelope);
+  trim(envelopes, limit);
+  return envelope;
+}
+
+export function recordStats(stats: ExpandStats): void {
+  for (const key of Object.keys(counts) as Array<keyof ExpandStats>) counts[key] += stats[key];
+}
+
+export function expandStats(): ExpandStats {
+  return { ...counts };
+}
+
+export function resetExpandStats(): void {
+  for (const key of Object.keys(counts) as Array<keyof ExpandStats>) counts[key] = 0;
+}
+
+export function clearExpandCache(): void {
+  occurrences.clear();
+  envelopes.clear();
+}

package/src/adapters/rrule/envelope.ts

@@ -0,0 +1,7 @@
+import type { Window } from '../../core';
+
+// Absolute 48-hour padding exceeds the 26-hour difference between view zones.
+// Includes, excludes, and dates share these bounds before subtraction.
+export function envelopeFor(window: Window): Window {
+  return { start: window.start - 48 * 3_600_000, end: window.end + 48 * 3_600_000 };
+}

package/src/adapters/rrule/expand.ts

@@ -0,0 +1,105 @@
+import type { Interval, Source, Window } from '../../core';
+import { occurrences, recordStats, retainedEnvelope, touch, trim } from './cache';
+import { envelopeFor } from './envelope';
+import { bodyKey } from './hash';
+import { net } from './net';
+import { enumerate, validateDates } from './occurrences';
+import type {
+  ExpandOptions,
+  ExpandResult,
+  ExpandStats,
+  RosterDate,
+  RosterRule,
+  RuleSet,
+} from './types';
+import { nonnegativeInteger, validateInput, validateWindow } from './validate';
+
+export function expandRuleSet(
+  set: RuleSet,
+  window: Window,
+  options: ExpandOptions = {},
+): ExpandResult {
+  validateWindow(window);
+  const maxEntries = nonnegativeInteger(options.cache?.maxEntries ?? 2000, 'cache.maxEntries');
+  const maxEnvelopes = nonnegativeInteger(options.cache?.maxEnvelopes ?? 4, 'cache.maxEnvelopes');
+  const cap = nonnegativeInteger(
+    options.caps?.perRuleOccurrences ?? 400,
+    'caps.perRuleOccurrences',
+  );
+  let remaining = nonnegativeInteger(
+    options.caps?.totalOccurrences ?? 10000,
+    'caps.totalOccurrences',
+  );
+  const rules = [...set.rules].sort(byId);
+  const dates = [...set.dates].sort(byId);
+  const ordered = [...rules, ...dates];
+  for (const input of ordered) {
+    validateInput(input);
+    validateDates(input);
+  }
+  const stats: ExpandStats = {
+    rules: set.rules.length,
+    dates: set.dates.length,
+    expanded: 0,
+    cacheHits: 0,
+    cacheMisses: 0,
+  };
+  if (window.start === window.end) {
+    recordStats(stats);
+    return {
+      intervals: [],
+      gaps: [],
+      envelope: envelopeFor(window),
+      complete: true,
+      truncated: [],
+      stats,
+    };
+  }
+  const envelope = retainedEnvelope(window, maxEnvelopes);
+  trim(occurrences, maxEntries);
+  const includes: Interval[] = [];
+  const excludes: Interval[] = [];
+  const truncated: ExpandResult['truncated'] = [];
+  let dropped = false;
+  for (const input of ordered) {
+    const key = JSON.stringify([bodyKey(input), envelope.start, envelope.end, cap]);
+    let list = occurrences.get(key);
+    if (list) {
+      touch(occurrences, key, list);
+      stats.cacheHits++;
+    } else {
+      list = enumerate(input, envelope, cap);
+      touch(occurrences, key, list);
+      trim(occurrences, maxEntries);
+      stats.expanded++;
+      stats.cacheMisses++;
+    }
+    // No partial admission: the first list that cannot fit ends the admitted
+    // prefix. Fetch all later lists anyway to report their exact retained counts.
+    dropped ||= list.spans.length > remaining;
+    if (dropped || list.capped) {
+      truncated.push({
+        id: input.id,
+        droppedAtLeast: list.capped ? 1 : list.spans.length,
+      });
+    }
+    if (dropped) continue;
+    remaining -= list.spans.length;
+    const source: Source = { kind: 'date' in input ? 'date' : 'rule', id: input.id };
+    if ('date' in input && input.note !== undefined) source.label = input.note;
+    const target = input.kind === 'include' ? includes : excludes;
+    for (const span of list.spans) target.push({ ...span, sources: [source] });
+  }
+  recordStats(stats);
+  return {
+    ...net(includes, excludes, window),
+    envelope: { ...envelope },
+    complete: truncated.length === 0,
+    truncated,
+    stats,
+  };
+}
+
+function byId(a: RosterRule | RosterDate, b: RosterRule | RosterDate): number {
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}

package/src/adapters/rrule/hash.ts

@@ -0,0 +1,13 @@
+import { structuralKey } from '../../core/hash';
+import type { RosterDate, RosterRule } from './types';
+
+// Use the core's collision-free canonical encoding as the content hash.
+// Identity and display notes are attached fresh, never cached in occurrence lists.
+export function bodyKey(input: RosterRule | RosterDate): string {
+  const { id: _id, ...body } = input;
+  if ('date' in body) {
+    const { note: _note, ...date } = body;
+    return structuralKey(date);
+  }
+  return structuralKey(body);
+}

package/src/adapters/rrule/index.ts

@@ -0,0 +1,11 @@
+export { clearExpandCache, expandStats, resetExpandStats } from './cache';
+export { envelopeFor } from './envelope';
+export { expandRuleSet } from './expand';
+export type {
+  ExpandOptions,
+  ExpandResult,
+  ExpandStats,
+  RosterDate,
+  RosterRule,
+  RuleSet,
+} from './types';

package/src/adapters/rrule/net.ts

@@ -0,0 +1,30 @@
+import type { Gap, Interval, Window } from '../../core';
+import { sourceSpans } from '../../core/spans';
+
+export function net(
+  includes: Interval[],
+  excludes: Interval[],
+  window: Window,
+): { intervals: Interval[]; gaps: Gap[] } {
+  const covered = sourceSpans(includes, window);
+  const removed = sourceSpans(excludes, window);
+  const intervals: Interval[] = [];
+  const gaps: Gap[] = [];
+  let first = 0;
+  for (const include of covered) {
+    let start = include.start;
+    while (first < removed.length && (removed[first] as Gap).end <= start) first++;
+    for (let i = first; i < removed.length; i++) {
+      const exclude = removed[i] as Gap;
+      if (exclude.start >= include.end) break;
+      if (start < exclude.start)
+        intervals.push({ start, end: exclude.start, sources: include.sources });
+      const end = Math.min(include.end, exclude.end);
+      gaps.push({ start: Math.max(start, exclude.start), end, sources: exclude.sources });
+      start = end;
+    }
+    if (start < include.end) intervals.push({ start, end: include.end, sources: include.sources });
+  }
+  // Include source changes cannot split an otherwise identical removed span.
+  return { intervals, gaps: sourceSpans(gaps, window) };
+}