@instructure/platform-modules 0.1.0

package/dist/components/StatusPill.d.ts

@@ -0,0 +1,18 @@
+import { ReactElement } from 'react';
+import { TranslateFunction } from '../i18n';
+import { ModuleItemStatus, ModuleStatus } from '../types';
+/** Exhaustive: a new `ModuleStatus` is a compile error until it has a label. */
+export declare function moduleStatusLabel(t: TranslateFunction, status: ModuleStatus): string;
+/** @see moduleStatusLabel */
+export declare function moduleItemStatusLabel(t: TranslateFunction, status: ModuleItemStatus): string;
+export interface ModuleStatusPillProps {
+    status: ModuleStatus;
+}
+/** @see ModuleStatusPillProps */
+export declare function ModuleStatusPill({ status }: ModuleStatusPillProps): ReactElement;
+export interface ModuleItemStatusPillProps {
+    status: ModuleItemStatus;
+}
+/** @see ModuleItemStatusPillProps */
+export declare function ModuleItemStatusPill({ status }: ModuleItemStatusPillProps): ReactElement;
+//# sourceMappingURL=StatusPill.d.ts.map

package/dist/components/StatusPill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatusPill.d.ts","sourceRoot":"","sources":["../../src/components/StatusPill.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AACzC,OAAO,EAAE,KAAK,iBAAiB,EAAkB,MAAM,SAAS,CAAA;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AA4C9D,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAepF;AAED,6BAA6B;AAC7B,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAe5F;AAUD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,YAAY,CAAA;CACrB;AAED,iCAAiC;AACjC,wBAAgB,gBAAgB,CAAC,EAAE,MAAM,EAAE,EAAE,qBAAqB,GAAG,YAAY,CAOhF;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,gBAAgB,CAAA;CACzB;AAED,qCAAqC;AACrC,wBAAgB,oBAAoB,CAAC,EAAE,MAAM,EAAE,EAAE,yBAAyB,GAAG,YAAY,CAOxF"}

package/dist/components/index.d.ts

@@ -0,0 +1,7 @@
+export { FilterChips, type FilterChipsProps } from './FilterChips';
+export { calendarDayDiff, DUE_THIS_WEEK_DAYS, filterLabel, formatDateTime, formatDueByline, formatModuleNumber, formatPoints, formatUnlockByline, itemTypeLabel, moduleMatchesFilter, moduleMatchesSearch, MODULES_FILTER_IDS, type ModulesFilterId, progressSummary, requirementLabel, } from './labels';
+export { ModuleCard, type ModuleCardProps } from './ModuleCard';
+export { ModuleItemRow, type ModuleItemRowProps } from './ModuleItemRow';
+export { ModulesList, type ModulesListProps, type ModulesRequestCounts } from './ModulesList';
+export { moduleItemStatusLabel, ModuleItemStatusPill, type ModuleItemStatusPillProps, moduleStatusLabel, ModuleStatusPill, type ModuleStatusPillProps, } from './StatusPill';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAClE,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,eAAe,EACpB,eAAe,EACf,gBAAgB,GACjB,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAC/D,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACxE,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAC7F,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,yBAAyB,EAC9B,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAA"}

package/dist/components/labels.d.ts

@@ -0,0 +1,89 @@
+import { TranslateFunction } from '../i18n';
+import { CompletionRequirement, Module, ModuleItemType } from '../types';
+/** A locale-aware number formatter, cached. Exported so components share the cache. */
+export declare function numberFormatterFor(locale?: string): Intl.NumberFormat;
+/** Whole calendar days between two dates, ignoring the time of day. */
+export declare function calendarDayDiff(a: Date, b: Date): number;
+/**
+ * "today, 11:59 PM" / "yesterday, 11:59 PM" / "January 12, 11:59 PM".
+ *
+ * The relative words are separate keys rather than one string with a placeholder,
+ * because a language that puts the time first, or inflects "yesterday" by what
+ * follows it, needs to move the pieces independently.
+ *
+ * No timezone suffix. The domain model carries none and this package may not read
+ * one off the host, so printing one would be a guess — see `src/i18n.tsx`.
+ */
+export declare function formatDateTime(t: TranslateFunction, iso: string, today: Date, locale?: string): string;
+/** The module header byline when the module is open: "Due yesterday, 11:59 PM". */
+export declare function formatDueByline(t: TranslateFunction, iso: string, today: Date, locale?: string): string;
+/** The module header byline when the module is locked. */
+export declare function formatUnlockByline(t: TranslateFunction, iso: string, today: Date, locale?: string): string;
+/**
+ * "01", "02", … "120". Two-digit minimum, matching the design's badge.
+ *
+ * Localised through `Intl.NumberFormat` rather than `String(n).padStart`, because
+ * the badge is a number and locales that use different digits should show theirs.
+ */
+export declare function formatModuleNumber(position: number, locale?: string): string;
+export declare function itemTypeLabel(t: TranslateFunction, type: ModuleItemType): string;
+/** "10 pts". Null/undefined points render nothing at all, not "0 pts". */
+export declare function formatPoints(t: TranslateFunction, pointsPossible: number | null | undefined, locale?: string): string | null;
+/**
+ * The requirement column, e.g. "Submit the assignment".
+ *
+ * Exhaustive over `CompletionRequirementType` — no `default`, so adding a member
+ * to the enum is a compile error here rather than a silently unlabelled row. The
+ * `unknown` member is what absorbs a seventh Canvas type, and it still renders
+ * something: an unlabelled requirement would look like *no* requirement, which
+ * is the wrong failure.
+ */
+export declare function requirementLabel(t: TranslateFunction, requirement: CompletionRequirement, locale?: string): string;
+/**
+ * "75% | 3 of 4 requirements met", straight off the design.
+ *
+ * The `|` is baked into the translatable string, which is not ideal — a translator
+ * cannot tell it is a divider rather than punctuation, and a screen reader may
+ * either skip it or announce "vertical bar". Left as one key because splitting it
+ * changes the design's copy; flagged rather than quietly restructured.
+ */
+export declare function progressSummary(t: TranslateFunction, percentComplete: number, met: number, total: number, locale?: string): string;
+export type ModulesFilterId = 'all' | 'in_progress' | 'complete' | 'due_this_week' | 'missing';
+/**
+ * The chip order the design draws, as ids only.
+ *
+ * Ids rather than `{ id, label }` pairs because a label is now a function of the
+ * host's `t`, and a module-level constant cannot call one. `filterLabel` supplies
+ * the text.
+ */
+export declare const MODULES_FILTER_IDS: readonly ModulesFilterId[];
+export declare function filterLabel(t: TranslateFunction, id: ModulesFilterId): string;
+/** How far ahead "Due this week" looks. */
+export declare const DUE_THIS_WEEK_DAYS = 7;
+/**
+ * Filter chips are **module-level only**, by design.
+ *
+ * Every predicate reads `module.progress`, which the adapter returns with the
+ * module list. None of them touch items. That is deliberate: in `onDemand` mode
+ * the items of a collapsed module have not been fetched, so an item-level
+ * filter would either lie or cost one request per module. The designer's
+ * annotation says the filters describe the *module's* overall status, which is
+ * exactly the cheap version.
+ *
+ * A module with no `progress` (teacher/anonymous view) matches only "All" —
+ * "we did not fetch progress" is not the same as "not in progress".
+ */
+export declare function moduleMatchesFilter(module: Module, filter: ModulesFilterId, today: Date): boolean;
+/**
+ * Search matches **module names only**, never item titles.
+ *
+ * Same reason as the filters: with `onDemand` pagination the items of collapsed
+ * modules are not in memory, so an item-level search would silently under-report
+ * — the one thing this package exists to prevent. The input is labelled
+ * "Search module names" so the limit is on screen rather than in a comment.
+ *
+ * `toLocaleLowerCase` rather than `toLowerCase`: the Turkish dotless i is the
+ * standard counterexample, and a course in Turkish should find its own modules.
+ */
+export declare function moduleMatchesSearch(module: Module, query: string, locale?: string): boolean;
+//# sourceMappingURL=labels.d.ts.map

package/dist/components/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../../src/components/labels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAEhD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AA0D7E,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,MAAuB,GAAG,IAAI,CAAC,YAAY,CAErF;AAeD,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAIxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,iBAAiB,EACpB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,IAAI,EACX,MAAM,GAAE,MAAuB,GAC9B,MAAM,CAiBR;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAC7B,CAAC,EAAE,iBAAiB,EACpB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,IAAI,EACX,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAER;AAED,0DAA0D;AAC1D,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,iBAAiB,EACpB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,IAAI,EACX,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,MAAuB,GAAG,MAAM,CAE5F;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAmBhF;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAC1B,CAAC,EAAE,iBAAiB,EACpB,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,MAAM,GAAE,MAAuB,GAC9B,MAAM,GAAG,IAAI,CAGf;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,iBAAiB,EACpB,WAAW,EAAE,qBAAqB,EAClC,MAAM,GAAE,MAAuB,GAC9B,MAAM,CAuBR;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE,iBAAiB,EACpB,eAAe,EAAE,MAAM,EACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAuB,GAC9B,MAAM,CAOR;AAID,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,aAAa,GAAG,UAAU,GAAG,eAAe,GAAG,SAAS,CAAA;AAE9F;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAMxD,CAAA;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,iBAAiB,EAAE,EAAE,EAAE,eAAe,GAAG,MAAM,CAa7E;AAED,2CAA2C;AAC3C,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAqCjG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAI3F"}

package/dist/config/index.d.ts

@@ -0,0 +1,3 @@
+export { mergeRegistry, visibleEntries, type Registry, type RegistryOverride, type VisibleEntry, } from './registry';
+export { registrySchema, RegistryEntrySchema, type RegistryEntry } from './schemas';
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA"}

package/dist/config/registry.d.ts

@@ -0,0 +1,38 @@
+import { RegistryEntry } from './schemas';
+/**
+ * The registry primitive: merge one over another, then read the visible entries
+ * in a deterministic order. No React, no validation — the schemas in
+ * `./schemas` validate once, at config resolution.
+ */
+export type Registry<E extends RegistryEntry = RegistryEntry> = Record<string, E>;
+/** `Partial<E>` because an overlay states only what it changes. An addition still needs a whole entry, which only the schema can enforce. */
+export type RegistryOverride<E extends RegistryEntry = RegistryEntry> = Record<string, Partial<E>>;
+export type VisibleEntry<E extends RegistryEntry = RegistryEntry> = E & {
+    key: string;
+};
+/**
+ * Fold an override over a base registry, one entry at a time:
+ * `{ ...base[key], ...override[key] }`. A key the base has is an overlay; a key
+ * it doesn't is an addition.
+ *
+ * Key order of the result is what `visibleEntries` breaks ties on: base keys in
+ * base order, then additions sorted by key so a host cannot change the rendered
+ * order by reordering its own literal.
+ *
+ * Copies every entry, so neither argument is mutated or shared. Built by spread
+ * rather than assignment, and keyed by own properties only, so an override
+ * parsed from host JSON cannot reach `Object.prototype` through a `__proto__`
+ * or `constructor` key.
+ */
+export declare function mergeRegistry<E extends RegistryEntry>(base: Registry<E>, override?: RegistryOverride<E>): Registry<E>;
+/**
+ * The entries a host has left switched on, sorted by `order` ascending.
+ *
+ * Ties fall through to key order, per `mergeRegistry` above — `Array#sort` is
+ * stable by specification from ES2019.
+ *
+ * Filtering `hidden` here rather than at the merge is what lets a host inspect
+ * what it turned off.
+ */
+export declare function visibleEntries<E extends RegistryEntry>(registry: Registry<E>): ReadonlyArray<VisibleEntry<E>>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/config/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/config/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAE9C;;;;GAIG;AAEH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;AAEjF,6IAA6I;AAC7I,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;AAElG,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IAAI,CAAC,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAavF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,aAAa,EACnD,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,QAAQ,GAAE,gBAAgB,CAAC,CAAC,CAAM,GACjC,QAAQ,CAAC,CAAC,CAAC,CAYb;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EACpD,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GACpB,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAKhC"}

package/dist/config/schemas.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/**
+ * The shape every registry entry shares, schema first so the type is inferred
+ * from one list of fields — same inversion as `types/enums.ts`.
+ *
+ * Registries are validated at runtime rather than typed with generics, because
+ * a host may fetch one. See `docs/adr/0001-customization.md`.
+ */
+export declare const RegistryEntrySchema: z.ZodObject<{
+    label: z.ZodString;
+    order: z.ZodNumber;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+}>;
+export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;
+export declare function registrySchema<E extends RegistryEntry>(entrySchema: z.ZodType<E>): z.ZodRecord<z.ZodString, z.ZodType<E>>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/config/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/config/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,SAAS,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC,SAAS,CAAA;IAClB,KAAK,EAAE,CAAC,CAAC,SAAS,CAAA;IAClB,MAAM,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAA;CACpC,CASC,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EACpD,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACxB,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAExC"}

package/dist/fixtures/generate.d.ts

@@ -0,0 +1,48 @@
+import { InMemoryFixture } from '../adapters/inMemory';
+import { ModuleStatus } from '../types/domain';
+/**
+ * The full `ModuleStatus` enum, one per module, cycled.
+ *
+ * Exported because it is also the reason `SMALL_MODULE_COUNT` is what it is:
+ * a fixture shorter than this cycle cannot show every state.
+ */
+export declare const MODULE_STATUS_CYCLE: readonly ModuleStatus[];
+/** The course every fixture belongs to; only used to build plausible URLs. */
+export declare const FIXTURE_COURSE_ID = "1";
+/**
+ * Build a fixture from a per-module item count, e.g. `[8, 250, 8]` is three
+ * modules where the middle one is far past the inline limit.
+ */
+/**
+ * Which audience the fixture describes.
+ *
+ * Not cosmetic: the two shapes are mutually exclusive in Canvas, and a fixture
+ * that mixes them describes a page no host can ever render.
+ *
+ * - `student` — everything is published, and every module carries a `progress`
+ *   with every item a `status`. A student's module list contains no unpublished
+ *   content at all; that is exactly why normalisation rule 2 reads a null
+ *   `published` as `true` for a viewer without manage permission.
+ * - `teacher` — publish state varies, and nothing carries progress. Canvas
+ *   resolves `progression` to null for a viewer with no progression record, so a
+ *   teacher fixture with a `progress` would be describing a student.
+ *
+ * The bug this fixes: the generator used to emit unpublished modules *and*
+ * student progress on the same module, so `courseSmall`'s module 4 rendered as
+ * "(unpublished)" next to a progress bar — a combination that cannot occur.
+ */
+export type FixtureView = 'student' | 'teacher';
+export interface BuildFixtureOptions {
+    /** Defaults to `student`. */
+    view?: FixtureView;
+    /**
+     * Which course the fixture is for. Defaults to `FIXTURE_COURSE_ID` ('1').
+     *
+     * Override it to prove a hook actually threads `courseId` through: with every
+     * fixture on course '1', a hook that hardcoded '1' internally would be
+     * indistinguishable from one that passed the caller's value.
+     */
+    courseId?: string;
+}
+export declare function buildFixture(itemCounts: readonly number[], options?: BuildFixtureOptions): InMemoryFixture;
+//# sourceMappingURL=generate.d.ts.map

package/dist/fixtures/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/fixtures/generate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAQV,YAAY,EACb,MAAM,iBAAiB,CAAA;AA4DxB;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,YAAY,EAOtD,CAAA;AA0BD,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,MAAM,CAAA;AA2PpC;;;GAGG;AACH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,CAAA;AAE/C,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAgBD,wBAAgB,YAAY,CAC1B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,OAAO,GAAE,mBAAwB,GAChC,eAAe,CAiBjB"}

package/dist/fixtures/index.d.ts

@@ -0,0 +1,3 @@
+export { buildFixture, type BuildFixtureOptions, FIXTURE_COURSE_ID, type FixtureView, MODULE_STATUS_CYCLE, } from './generate';
+export { courseEmpty, courseFatModule, courseLarge, courseSmall, FAT_MODULE_ITEM_COUNT, FAT_MODULE_SIBLING_ITEM_COUNT, LARGE_ITEMS_PER_MODULE, LARGE_MODULE_COUNT, SMALL_ITEMS_PER_MODULE, SMALL_MODULE_COUNT, } from './scenarios';
+//# sourceMappingURL=index.d.ts.map

package/dist/fixtures/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fixtures/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,iBAAiB,EACjB,KAAK,WAAW,EAChB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,WAAW,EACX,eAAe,EACf,WAAW,EACX,WAAW,EACX,qBAAqB,EACrB,6BAA6B,EAC7B,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAA"}

package/dist/fixtures/scenarios.d.ts

@@ -0,0 +1,42 @@
+import { InMemoryFixture } from '../adapters/inMemory';
+/**
+ * Four named scales. Each one exists to make a specific failure impossible to
+ * ship silently, so they are sized against real Canvas limits rather than
+ * chosen for convenience.
+ */
+/**
+ * 6 modules × 8 items. Inline mode resolves; the whole course in ~2 requests.
+ *
+ * The module count is `MODULE_STATUS_CYCLE.length` rather than a round number:
+ * this is the fixture a story reaches for by default, and at five modules it
+ * would silently omit one of the six `ModuleStatus` states.
+ */
+export declare const SMALL_MODULE_COUNT: number;
+export declare const SMALL_ITEMS_PER_MODULE = 8;
+/** 120 modules × 25 items. Past the 100-per-page module limit Career truncates at. */
+export declare const LARGE_MODULE_COUNT = 120;
+export declare const LARGE_ITEMS_PER_MODULE = 25;
+/** 3 modules, the middle one 250 items — 2.5× `INLINE_ITEM_LIMIT`. */
+export declare const FAT_MODULE_ITEM_COUNT = 250;
+export declare const FAT_MODULE_SIBLING_ITEM_COUNT = 8;
+/**
+ * The happy path: everything fits in one page of modules with items inlined,
+ * so a correct implementation renders the course in about two requests.
+ */
+export declare function courseSmall(): InMemoryFixture;
+/**
+ * Module-list pagination past 100. Canvas caps `per_page` at 100, so a client
+ * that ignores the next cursor shows 100 of 120 modules and says nothing —
+ * which is what Canvas Career does today.
+ */
+export declare function courseLarge(): InMemoryFixture;
+/**
+ * Item pagination past `INLINE_ITEM_LIMIT`. Canvas omits the `items` key
+ * entirely for the fat module, so the client must fall back to a per-module
+ * fetch and then page it. The "renders exactly 100 items and stops" bug lives
+ * here and cannot recur while this fixture is in the suite.
+ */
+export declare function courseFatModule(): InMemoryFixture;
+/** No modules at all. The empty state exists before the designs specify it. */
+export declare function courseEmpty(): InMemoryFixture;
+//# sourceMappingURL=scenarios.d.ts.map

package/dist/fixtures/scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenarios.d.ts","sourceRoot":"","sources":["../../src/fixtures/scenarios.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAG3D;;;;GAIG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAmC,CAAA;AACpE,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC,sFAAsF;AACtF,eAAO,MAAM,kBAAkB,MAAM,CAAA;AACrC,eAAO,MAAM,sBAAsB,KAAK,CAAA;AAExC,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,MAAM,CAAA;AACxC,eAAO,MAAM,6BAA6B,IAAI,CAAA;AAE9C;;;GAGG;AACH,wBAAgB,WAAW,IAAI,eAAe,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,eAAe,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAMjD;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,IAAI,eAAe,CAE7C"}

package/dist/hooks/constants.d.ts

@@ -0,0 +1,49 @@
+import { PageInfo } from '../types/domain';
+/** Canvas's `Api::MAX_PER_PAGE`. One page of modules per request by default. */
+export declare const DEFAULT_PAGE_SIZE: number;
+/** Items are paged separately; same ceiling. */
+export declare const DEFAULT_ITEM_PAGE_SIZE: number;
+/**
+ * Per-module ceiling above which inlining stops being worthwhile.
+ *
+ * Matches `Api::MAX_PER_PAGE` and `INLINE_ITEM_LIMIT`. On REST that is Canvas's
+ * own rule — the `items` key is simply absent above it. On GraphQL it is this
+ * package's policy rather than a server constraint. @see INLINE_ITEM_LIMIT
+ */
+export declare const DEFAULT_INLINE_THRESHOLD: number;
+/**
+ * How many per-module item requests may be in flight at once.
+ *
+ * Expanding "all modules" on a 40-module course should not open 40 sockets;
+ * browsers queue them anyway, but the server sees the whole burst.
+ */
+export declare const DEFAULT_ITEM_CONCURRENCY: number;
+/**
+ * Why this is not zero.
+ *
+ * With `staleTime: 0` every re-enable of a query — which is what re-expanding a
+ * module is — counts as stale and refetches. That is the behaviour this package
+ * exists to remove. Five minutes is long enough that expand/collapse within a
+ * sitting is free, short enough that coming back to the tab later is honest.
+ */
+export declare const DEFAULT_STALE_TIME_MS: number;
+/**
+ * How many *collapsed* modules keep their item query subscribed.
+ *
+ * A collapsed module's observer is retained on purpose — that is what makes
+ * re-expanding a guaranteed cache hit rather than a lucky one. But retention has
+ * to stop somewhere: "Expand all" followed by "Collapse all" on a 120-module
+ * course would otherwise leave 120 subscriptions alive for the life of the page,
+ * each pinning its own pages of items past any `gcTime`.
+ *
+ * Twenty is chosen against the interaction rather than the data: a reader moving
+ * through a course revisits the handful of modules around where they are, and
+ * twenty covers that with room to spare while keeping the retained set a fixed
+ * cost instead of one that grows with course size. Above the cap the
+ * least-recently-active collapsed module is evicted, and re-expanding it may
+ * refetch.
+ */
+export declare const DEFAULT_RETAIN_COLLAPSED_LIMIT: number;
+/** The pageInfo of a query that has not resolved yet. Never truncates silently. */
+export declare const EMPTY_PAGE_INFO: PageInfo;
+//# sourceMappingURL=constants.d.ts.map

package/dist/hooks/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/hooks/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE/C,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,EAAE,MAAY,CAAA;AAE5C,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,EAAE,MAAY,CAAA;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAY,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAU,CAAA;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAsB,CAAA;AAE1D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,8BAA8B,EAAE,MAAW,CAAA;AAExD,mFAAmF;AACnF,eAAO,MAAM,eAAe,EAAE,QAAkD,CAAA"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export { DEFAULT_INLINE_THRESHOLD, DEFAULT_ITEM_CONCURRENCY, DEFAULT_ITEM_PAGE_SIZE, DEFAULT_PAGE_SIZE, DEFAULT_RETAIN_COLLAPSED_LIMIT, DEFAULT_STALE_TIME_MS, EMPTY_PAGE_INFO, } from './constants';
+export { moduleItemsQueryOptions, modulesQueryOptions, type ModuleItemsQueryArgs, type ModuleItemsQueryOptions, type ModulesCursor, type ModulesQueryArgs, type ModulesQueryOptions, } from './queryOptions';
+export { useModules, type UseModulesOptions, type UseModulesResult } from './useModules';
+export { useModuleItems, type UseModuleItemsOptions, type UseModuleItemsResult, } from './useModuleItems';
+export { resolveItemsMode, inlineShapeOf, type InlineQueryShape, useItemsMode, type ItemsMode, type ResolvedItemsMode, type UseItemsModeOptions, type UseItemsModeResult, } from './useItemsMode';
+export { useModulesPageData, type ModuleItemsSource, type ModuleItemsState, type UseModulesPageDataOptions, type UseModulesPageDataResult, } from './useModulesPageData';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EACjB,8BAA8B,EAC9B,qBAAqB,EACrB,eAAe,GAChB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACxF,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,KAAK,gBAAgB,EACrB,YAAY,EACZ,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAA"}

package/dist/hooks/queryOptions.d.ts

@@ -0,0 +1,58 @@
+import { InfiniteData, InfiniteQueryObserverOptions } from '@tanstack/react-query';
+import { LimitFunction } from 'p-limit';
+import { ModulesDataAdapter } from '../adapters/types';
+import { ModuleItemsKey, ModulesListKey, ModulesView } from '../cache/keys';
+import { ModuleItemsPage, ModulesPage } from '../types/domain';
+/**
+ * The two query definitions this package has, factored out of the hooks.
+ *
+ * They live here because the same definition is consumed two ways: through
+ * `useInfiniteQuery` (one module, one hook) and through a raw
+ * `InfiniteQueryObserver` (a dynamic set of expanded modules, which React's
+ * rules of hooks will not let you express as N `useInfiniteQuery` calls).
+ * Sharing the factory is what guarantees both paths land on the *same* cache
+ * entry, so a module fetched by one is a cache hit for the other.
+ */
+/**
+ * The page cursor. `null` is the first page — the adapter contract forbids
+ * synthesising cursors, so this is only ever `null` or something a server said.
+ */
+export type ModulesCursor = string | null;
+export type ModulesQueryOptions = InfiniteQueryObserverOptions<ModulesPage, Error, InfiniteData<ModulesPage, ModulesCursor>, ModulesListKey, ModulesCursor>;
+export type ModuleItemsQueryOptions = InfiniteQueryObserverOptions<ModuleItemsPage, Error, InfiniteData<ModuleItemsPage, ModulesCursor>, ModuleItemsKey, ModulesCursor>;
+export interface ModulesQueryArgs {
+    courseId: string;
+    adapter: ModulesDataAdapter;
+    pageSize: number;
+    includeItems: boolean;
+    /** Items to request per module when inlining. @see ListModulesArgs.inlineItemsFirst */
+    inlineItemsFirst?: number;
+    /** Modules to request when inlining. @see ListModulesArgs.inlineFirst */
+    inlineFirst?: number;
+    view?: ModulesView;
+    staleTime: number;
+    enabled: boolean;
+}
+export interface ModuleItemsQueryArgs {
+    courseId: string;
+    moduleId: string;
+    adapter: ModulesDataAdapter;
+    pageSize: number;
+    /**
+     * The audience this page is rendered for. Not sent to the adapter — a host
+     * configures its adapter for the current user — but it partitions the key,
+     * because `published` is a per-item field. See `ModuleItemsKeyOptions`.
+     */
+    view?: ModulesView;
+    staleTime: number;
+    enabled: boolean;
+    /**
+     * Shared concurrency gate. Every expanded module's item fetch goes through
+     * the same limiter instance, so "expand all" is a trickle rather than a
+     * thundering herd.
+     */
+    limit?: LimitFunction;
+}
+export declare function modulesQueryOptions(args: ModulesQueryArgs): ModulesQueryOptions;
+export declare function moduleItemsQueryOptions(args: ModuleItemsQueryArgs): ModuleItemsQueryOptions;
+//# sourceMappingURL=queryOptions.d.ts.map

package/dist/hooks/queryOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryOptions.d.ts","sourceRoot":"","sources":["../../src/hooks/queryOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAA;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAEnE;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,IAAI,CAAA;AAEzC,MAAM,MAAM,mBAAmB,GAAG,4BAA4B,CAC5D,WAAW,EACX,KAAK,EACL,YAAY,CAAC,WAAW,EAAE,aAAa,CAAC,EACxC,cAAc,EACd,aAAa,CACd,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG,4BAA4B,CAChE,eAAe,EACf,KAAK,EACL,YAAY,CAAC,eAAe,EAAE,aAAa,CAAC,EAC5C,cAAc,EACd,aAAa,CACd,CAAA;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,kBAAkB,CAAA;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,OAAO,CAAA;IACrB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,kBAAkB,CAAA;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAYD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,mBAAmB,CAmC/E;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,GAAG,uBAAuB,CAyB3F"}

package/dist/hooks/useItemsMode.d.ts

@@ -0,0 +1,114 @@
+import { ModulesDataAdapter } from '../adapters/types';
+import { ModulesView } from '../cache/keys';
+import { ModulesPage } from '../types/domain';
+/**
+ * How a course's module items get fetched.
+ *
+ * - `inline` — ask for items alongside the module list. One round trip for the
+ *   whole page. Great for a small course, ruinous for a big one: the response
+ *   grows with the number of items, and no module over `inlineThreshold` is
+ *   inlined on either transport anyway (@see INLINE_ITEM_LIMIT).
+ * - `onDemand` — fetch a module's items when it is expanded. Constant-cost
+ *   first paint, one extra request per module the user actually opens.
+ * - `auto` — probe, then pick. The default.
+ */
+export type ItemsMode = 'auto' | 'inline' | 'onDemand';
+/** What `auto` collapses to. */
+export type ResolvedItemsMode = 'inline' | 'onDemand';
+export interface UseItemsModeOptions {
+    courseId: string;
+    adapter: ModulesDataAdapter;
+    mode?: ItemsMode;
+    /** Per-module ceiling for inlining. Defaults to 100. @see INLINE_ITEM_LIMIT */
+    inlineThreshold?: number;
+    /**
+     * Ceiling on the implied request's node product.
+     *
+     * Defaults to what the adapter declares (`inlineNodeBudget`), then to
+     * `INLINE_QUERY_NODE_BUDGET`. Pass it only to override both.
+     */
+    nodeBudget?: number;
+    pageSize?: number;
+    view?: ModulesView;
+    staleTime?: number;
+}
+export interface UseItemsModeResult {
+    /** `null` while the `auto` probe is still in flight. */
+    resolvedMode: ResolvedItemsMode | null;
+    isResolving: boolean;
+    /** True when a probe request was actually needed — i.e. `mode` was `auto`. */
+    probed: boolean;
+    error: Error | null;
+    /**
+     * How many items to actually ask for per module when inlining, and how many
+     * modules to ask for — both measured from the probe rather than assumed.
+     *
+     * `null` when unknown (probe unresolved, or an explicit mode skipped it), in
+     * which case the adapter falls back to its own defaults.
+     *
+     * It exists because a transport can charge for the shape of the request rather
+     * than the size of the result, so asking for what the probe actually saw is
+     * what keeps an inline page deliverable. @see INLINE_QUERY_NODE_BUDGET
+     */
+    inlineShape: InlineQueryShape | null;
+}
+/** What an inline `listModules` should request, measured from the probe. */
+export interface InlineQueryShape {
+    /** Modules on page 1. */
+    moduleCount: number;
+    /** The largest `itemCount` among them. */
+    maxItemCount: number;
+}
+/**
+ * The policy itself, as a pure function over the probe's first page.
+ *
+ * Inline is chosen only when all three hold:
+ *
+ *   1. The first page is the whole list. If there is a second page of modules,
+ *      the course total is unknown, and guessing from a partial view is how you
+ *      end up inlining a 3000-item course. Conservative on purpose.
+ *   2. No single module exceeds `inlineThreshold`. Above it no adapter inlines
+ *      the module — REST because Canvas drops the `items` key, GraphQL because
+ *      this package declines to — so inlining buys nothing there and it would
+ *      need an on-demand fetch regardless.
+ *   3. The course total is within `inlineThreshold * 2`. One module at the
+ *      ceiling is fine; forty of them is a payload nobody asked for.
+ *   4. The implied request fits Canvas's complexity budget. Rules 1-3 bound the
+ *      *data*; this one bounds the *query*, and they are not the same thing.
+ *      @see INLINE_QUERY_NODE_BUDGET
+ *
+ * Exported so the policy can be unit-tested without React.
+ */
+export declare function resolveItemsMode(firstPage: ModulesPage, inlineThreshold: number, nodeBudget?: number): ResolvedItemsMode;
+/**
+ * Resolves the items mode for a course.
+ *
+ * An explicit `mode` skips the probe entirely — the probe query is disabled, so
+ * it costs zero requests.
+ *
+ * For `auto`, the probe *is* the module list query with `includeItems: false`.
+ * That matters: if the probe resolves to `onDemand`, the page's own list query
+ * has the identical cache key and the probe becomes the first page for free. A
+ * second request happens only when the answer is `inline`, because inlined
+ * modules are a genuinely different payload and get their own key.
+ *
+ * Known cost of that shape, in the `auto -> inline` case only: the probe query
+ * stays mounted and enabled on its own key alongside the list query's, since
+ * `cache/keys.ts` partitions on `includeItems`. So `invalidateModuleList` refetches
+ * both where one would do, and a course that changes shape between refetches can
+ * flip the resolved mode mid-session. Neither is wrong, but neither is free —
+ * disabling the probe once it has answered would fix the first and make the second
+ * explicit.
+ *
+ * The decision is read from page 1 only, so paging further into the list can
+ * never flip the mode out from under a rendered page.
+ */
+export declare function useItemsMode(options: UseItemsModeOptions): UseItemsModeResult;
+/**
+ * The smallest request that still returns the whole page inline.
+ *
+ * `maxItemCount` is at least 1 because `first: 0` is not a meaningful request,
+ * and a course of entirely empty modules should still round-trip.
+ */
+export declare function inlineShapeOf(firstPage: ModulesPage): InlineQueryShape;
+//# sourceMappingURL=useItemsMode.d.ts.map

package/dist/hooks/useItemsMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useItemsMode.d.ts","sourceRoot":"","sources":["../../src/hooks/useItemsMode.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAIlD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAA;AAEtD,gCAAgC;AAChC,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,UAAU,CAAA;AAErD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,kBAAkB,CAAA;IAC3B,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACtC,WAAW,EAAE,OAAO,CAAA;IACpB,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB;;;;;;;;;;OAUG;IACH,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAA;CACrC;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,WAAW,EACtB,eAAe,EAAE,MAAM,EACvB,UAAU,GAAE,MAAiC,GAC5C,iBAAiB,CAuBnB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CA6D7E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,WAAW,GAAG,gBAAgB,CAMtE"}

package/dist/hooks/useModuleItemQueries.d.ts

@@ -0,0 +1,56 @@
+import { InfiniteData, InfiniteQueryObserverResult } from '@tanstack/react-query';
+import { ModuleItemsPage } from '../types/domain';
+import { ModuleItemsQueryOptions, ModulesCursor } from './queryOptions';
+/**
+ * A dynamic set of module-item infinite queries.
+ *
+ * ## Why this is not N `useModuleItems` calls
+ *
+ * The number of expanded modules changes at runtime, and React's rules of hooks
+ * forbid a variable number of hook calls. `useQueries` would solve it for plain
+ * queries, but it builds `QueryObserver`s, not `InfiniteQueryObserver`s — there
+ * is no `useInfiniteQueries`. So this hook does what `useQueries` does
+ * internally: it owns a map of observers keyed by module id, subscribes to each,
+ * and republishes their results into React state.
+ *
+ * The observers are built from the same `moduleItemsQueryOptions` factory
+ * `useModuleItems` uses, so both paths hit the same cache entry.
+ *
+ * ## Why a collapsed module keeps its observer
+ *
+ * Collapsing flips a module's options to `enabled: false` and leaves the
+ * subscription in place, which pins the cache entry no matter how aggressive the
+ * host's `gcTime` is. Re-expanding is then a cache hit by construction rather
+ * than by luck.
+ *
+ * ## Why the retained set is nevertheless bounded
+ *
+ * "Bounded by the modules a user actually opened" is only reassuring while
+ * opening a module is a click. `ModulesList` has an "Expand all", which on the
+ * 120-module fixture would leave 120 subscribed `InfiniteQueryObserver`s alive
+ * for the life of the page — each pinning its own pages of items — even after
+ * the user collapsed the lot.
+ *
+ * So retention is capped at `retainCollapsedLimit` *collapsed* observers, evicted
+ * least-recently-active first. Active observers are never evicted, whatever the
+ * limit: they are the ones with something on screen. Eviction destroys the
+ * observer, which unpins its cache entry and lets the host's `gcTime` apply —
+ * meaning re-expanding an evicted module may refetch. That is the trade, and it
+ * is the right way round: a guaranteed cache hit on the last N modules touched
+ * beats an unbounded set of subscriptions.
+ */
+type ItemsData = InfiniteData<ModuleItemsPage, ModulesCursor>;
+export type ModuleItemsObserverResult = InfiniteQueryObserverResult<ItemsData, Error>;
+export interface ModuleItemQueries {
+    results: ReadonlyMap<string, ModuleItemsObserverResult>;
+    fetchNextPage: (moduleId: string) => void;
+}
+export declare function useModuleItemQueries(
+/** Modules whose items should be fetching right now. */
+activeModuleIds: readonly string[], 
+/** Must be referentially stable — memoise it in the caller. */
+buildOptions: (moduleId: string, enabled: boolean) => ModuleItemsQueryOptions, 
+/** @see DEFAULT_RETAIN_COLLAPSED_LIMIT */
+retainCollapsedLimit?: number): ModuleItemQueries;
+export {};
+//# sourceMappingURL=useModuleItemQueries.d.ts.map

package/dist/hooks/useModuleItemQueries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useModuleItemQueries.d.ts","sourceRoot":"","sources":["../../src/hooks/useModuleItemQueries.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,2BAA2B,EACjC,MAAM,uBAAuB,CAAA;AAG9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEtD,OAAO,KAAK,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,KAAK,SAAS,GAAG,YAAY,CAAC,eAAe,EAAE,aAAa,CAAC,CAAA;AAE7D,MAAM,MAAM,yBAAyB,GAAG,2BAA2B,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;AAUrF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAA;IACvD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;CAC1C;AAOD,wBAAgB,oBAAoB;AAClC,wDAAwD;AACxD,eAAe,EAAE,SAAS,MAAM,EAAE;AAClC,+DAA+D;AAC/D,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,uBAAuB;AAC7E,0CAA0C;AAC1C,oBAAoB,GAAE,MAAuC,GAC5D,iBAAiB,CAoGnB"}