@aglyn/aglyn 1.0.0-beta.269 → 1.0.0-beta.270

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/aglyn",
-  "version": "1.0.0-beta.269",
+  "version": "1.0.0-beta.270",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -37,16 +37,16 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.269",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.269",
-    "@aglyn/shared-data-types": "1.0.0-beta.269",
-    "@aglyn/shared-util-email": "1.0.0-beta.269",
-    "@aglyn/shared-util-first-touch": "1.0.0-beta.269",
-    "@aglyn/shared-util-http": "1.0.0-beta.269",
-    "@aglyn/shared-util-logger": "1.0.0-beta.269",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.269",
-    "@aglyn/shared-util-tools": "1.0.0-beta.269",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.269",
+    "@aglyn/shared-data-enums": "1.0.0-beta.270",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.270",
+    "@aglyn/shared-data-types": "1.0.0-beta.270",
+    "@aglyn/shared-util-email": "1.0.0-beta.270",
+    "@aglyn/shared-util-first-touch": "1.0.0-beta.270",
+    "@aglyn/shared-util-http": "1.0.0-beta.270",
+    "@aglyn/shared-util-logger": "1.0.0-beta.270",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.270",
+    "@aglyn/shared-util-tools": "1.0.0-beta.270",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.270",
     "@data-driven-forms/react-form-renderer": "^4.2.0",
     "@msgpack/msgpack": "^3.1.3",
     "@types/unist": "^3.0.3",

package/src/lib/app-utils/account-preferences.d.ts

@@ -0,0 +1,248 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * THE PREFERENCES A PERSON KEEPS ON THEIR ACCOUNT (AGL-3943).
+ *
+ * One documented shape on `users/{uid}`, read and written the same way by
+ * the console and both native apps (docs/mobile/native-navigation.md):
+ *
+ * | field | shape | cap |
+ * | -- | -- | -- |
+ * | `pinnedOrgs` | workspace ids, in the order the person keeps them | 5 |
+ * | `recentOrgs` | workspace ids, most recently opened first | 8 |
+ * | `starred` | {@link StarredItem}s, in the order they were starred | 50 |
+ * | `recents` | {@link RecentItem}s, most recently opened first | 30 |
+ * | `workspaceColors` | workspace id → `#RRGGBB` the person picked | 100 |
+ * | `appTheme` | {@link AppThemePrefs}, the apps' look, synced | — |
+ *
+ * The caps are held twice: here, by every writer, and by the Firestore rules,
+ * which refuse a write that grows a list past its cap. A list that is ALREADY
+ * past it (pins made before the cap, Zach 2026-10-18) may only shrink, so a
+ * person with seven pins can still unpin one; the console asks them once
+ * which five to keep, and until they answer the first five are the pins.
+ *
+ * A per-device override of the theme ("this device only") is the device's
+ * own, kept in local storage on each platform, and never written here.
+ *
+ * NO IMPORTS, on purpose: the native apps read these constants, types and
+ * the answers of these functions through the generated contracts, so it must
+ * stay a plain module.
+ */
+/** `users/{uid}` field holding the ids of the workspaces the person pinned. */
+export declare const PINNED_ORGS_FIELD = "pinnedOrgs";
+/** The most workspaces a person may pin, everywhere, the console included. */
+export declare const PINNED_ORGS_MAX = 5;
+/** `users/{uid}` field holding the workspaces opened most recently, newest first. */
+export declare const RECENT_ORGS_FIELD = "recentOrgs";
+/** How many recently opened workspaces are kept. */
+export declare const RECENT_ORGS_MAX = 8;
+/** How many recent workspaces the rail shows below the pins. */
+export declare const RAIL_RECENT_ORGS = 3;
+/** An account with this many workspaces or fewer sees them all on the rail. */
+export declare const RAIL_ALL_WORKSPACES_AT_MOST = 8;
+/** `users/{uid}` field holding the person's starred screens and records. */
+export declare const STARRED_FIELD = "starred";
+/** The most items a person may star. */
+export declare const STARRED_MAX = 50;
+/** `users/{uid}` field holding the screens and records opened most recently. */
+export declare const RECENTS_FIELD = "recents";
+/** How many recently opened screens and records are kept. */
+export declare const RECENTS_MAX = 30;
+/** `users/{uid}` field holding the color the person picked for each workspace. */
+export declare const WORKSPACE_COLORS_FIELD = "workspaceColors";
+/** The most workspaces a person may pick a color for. */
+export declare const WORKSPACE_COLORS_MAX = 100;
+/** `users/{uid}` field holding the apps' theme, synced across devices. */
+export declare const APP_THEME_FIELD = "appTheme";
+/** The longest label a starred or recent item keeps. */
+export declare const ACCOUNT_ITEM_LABEL_MAX = 120;
+/** A picked color: `#` and six hex digits. */
+export declare const ACCOUNT_COLOR_PATTERN = "^#[0-9A-Fa-f]{6}$";
+/** The color dot a starred item may carry, named so each platform draws it from its theme. */
+export type StarColor = 'blue' | 'purple' | 'pink' | 'red' | 'orange' | 'yellow' | 'green' | 'grey';
+/** Every star color, in the order the picker lists them. */
+export declare const STAR_COLORS: readonly StarColor[];
+/**
+ * A screen or a record the person can come back to: what it is, where it
+ * belongs, what it was called, and the native screen that opens it.
+ */
+export interface AccountItemRef {
+    /**
+     * `screen` for a place in the app (a nav manifest row), otherwise the
+     * one-box search kind of the record (`page`, `order`, `contact`, …).
+     */
+    kind: string;
+    /** The nav row id for a `screen`, otherwise the record's document id. */
+    id: string;
+    /** The workspace it belongs to. */
+    orgId: string;
+    /** The site, for an item that belongs to one. */
+    hostId?: string;
+    /** What it was called when it was starred or opened. */
+    label: string;
+    /** The native screen that opens it. */
+    screen: string;
+    /** That screen's params. */
+    params?: Record<string, string>;
+}
+/** One starred item. */
+export interface StarredItem extends AccountItemRef {
+    color?: StarColor;
+    starredAtMs: number;
+}
+/** One recently opened item. */
+export interface RecentItem extends AccountItemRef {
+    openedAtMs: number;
+}
+export type AppAppearance = 'system' | 'light' | 'dark';
+export type AppThemeName = 'aglyn' | 'quiet' | 'night' | 'ocean' | 'warm' | 'highContrast';
+export type AppDensity = 'comfortable' | 'compact';
+export type AppTextSize = 'system' | 'small' | 'medium' | 'large' | 'extraLarge';
+export type AppSidebarStyle = 'tinted' | 'plain';
+/** The apps' look, saved on the account so it follows the person to every device. */
+export interface AppThemePrefs {
+    /** Light, dark or the system's. */
+    appearance: AppAppearance;
+    /** The theme: rail, sidebar tint, surfaces and accent for light and dark together. */
+    theme: AppThemeName;
+    /** `theme` for the theme's own accent, or a `#RRGGBB` the person picked. */
+    accent: string;
+    density: AppDensity;
+    /** `system` follows Dynamic Type or the font scale; the rest are the Mac and Windows sizes. */
+    textSize: AppTextSize;
+    sidebarStyle: AppSidebarStyle;
+    /** The app icon's id: `aglyn`, or one of the alternates the apps ship. */
+    appIcon: string;
+    /** A workspace's own brand color tints the app while you are in it. */
+    useWorkspaceBrand: boolean;
+}
+/** What a person who never changed anything sees. */
+export declare const DEFAULT_APP_THEME: AppThemePrefs;
+/** Every value each closed theme field accepts, in the order a picker lists them. */
+export declare const APP_APPEARANCES: readonly AppAppearance[];
+export declare const APP_THEME_NAMES: readonly AppThemeName[];
+export declare const APP_DENSITIES: readonly AppDensity[];
+export declare const APP_TEXT_SIZES: readonly AppTextSize[];
+export declare const APP_SIDEBAR_STYLES: readonly AppSidebarStyle[];
+/** The longest app icon id. */
+export declare const APP_ICON_ID_MAX = 40;
+/** Whether a value is a picked color, `#` and six hex digits. */
+export declare function isAccountColor(value: unknown): value is string;
+/**
+ * Every id the person stored as pinned, in their order, without repeats.
+ *
+ * Anything that is not a list of non-empty strings reads as no pins, so a
+ * stray value can never take a switcher down. May hold more than
+ * {@link PINNED_ORGS_MAX} for an account that pinned before the cap; read
+ * {@link effectivePinnedOrgs} for the pins to show.
+ */
+export declare function readPinnedOrgs(profile: unknown): string[];
+/** The pins in force: the first {@link PINNED_ORGS_MAX} stored, until the person picks. */
+export declare function effectivePinnedOrgs(stored: readonly string[]): string[];
+/** The account pinned more than the cap before there was one, and has to pick which to keep. */
+export declare function pinnedOrgsOverCap(stored: readonly string[]): boolean;
+export type PinOrgOutcome = 'pinned' | 'alreadyPinned' | 'full';
+export interface PinOrgResult {
+    /** The pins after the request: unchanged unless `outcome` is `pinned`. */
+    pinned: string[];
+    outcome: PinOrgOutcome;
+}
+/**
+ * Pins a workspace at the end of the list, or says the list is full. A full
+ * list is never made room in quietly: the caller asks "Pinned is full.
+ * Replace one?" and calls {@link replacePinnedOrg} with the answer.
+ */
+export declare function pinOrg(pinned: readonly string[], orgId: string): PinOrgResult;
+/** The pins without one workspace. */
+export declare function unpinOrg(pinned: readonly string[], orgId: string): string[];
+/**
+ * The pins with `orgId` in the place `replacing` held — the answer to
+ * "Pinned is full. Replace one?". Unchanged when `replacing` is not pinned
+ * or `orgId` already is.
+ */
+export declare function replacePinnedOrg(pinned: readonly string[], replacing: string, orgId: string): string[];
+/**
+ * The answer to "Keep which 5?": the stored pins the person ticked, in the
+ * order they were pinned, never more than the cap.
+ */
+export declare function keepPinnedOrgs(stored: readonly string[], keep: readonly string[]): string[];
+/** The pins with one moved up (`-1`) or down (`1`) a place; unchanged at an end. */
+export declare function movePinnedOrg(pinned: readonly string[], orgId: string, offset: number): string[];
+/** The recently opened workspaces as stored, newest first. */
+export declare function readRecentOrgs(profile: unknown): string[];
+/** The recent workspaces after opening one: it moves to the front, the oldest falls off. */
+export declare function recordRecentOrg(recent: readonly string[], orgId: string): string[];
+/** What the workspace rail shows. */
+export interface RailWorkspaces {
+    /** Pinned, at the top, in the person's order. */
+    pinned: string[];
+    /** Below the divider: recently opened and not pinned, at most {@link RAIL_RECENT_ORGS}. */
+    recent: string[];
+    /** Every other workspace, for an account small enough to list them all. */
+    rest: string[];
+    /** Whether the last tile is "All workspaces", opening the searchable switcher. */
+    allTile: boolean;
+    /** How many workspaces the person belongs to, shown under the All tile. */
+    total: number;
+}
+/**
+ * The rail for one account: up to five pinned, a divider, up to three recent,
+ * then an "All workspaces (N)" tile. An account with
+ * {@link RAIL_ALL_WORKSPACES_AT_MOST} workspaces or fewer sees them all and
+ * no All tile, since there is nothing to hide. `orgIds` is every membership,
+ * in the switcher's order; an id the person no longer belongs to is ignored.
+ */
+export declare function railWorkspaces(orgIds: readonly string[], pinned: readonly string[], recent: readonly string[]): RailWorkspaces;
+/** One item's identity: the same screen or record in the same place. */
+export declare function accountItemKey(item: Pick<AccountItemRef, 'kind' | 'id' | 'orgId' | 'hostId'>): string;
+/** The starred items as stored, each well formed, without repeats, never more than the cap. */
+export declare function readStarred(profile: unknown): StarredItem[];
+export type StarOutcome = 'starred' | 'unstarred' | 'full';
+export interface StarResult {
+    /** The starred items after the request: unchanged when `outcome` is `full`. */
+    starred: StarredItem[];
+    outcome: StarOutcome;
+}
+/** Stars an item at the end of the list, or unstars it; a full list says so instead. */
+export declare function toggleStarred(starred: readonly StarredItem[], item: AccountItemRef, nowMs: number): StarResult;
+/** The starred items with one item's color dot set, or cleared with `null`. */
+export declare function setStarColor(starred: readonly StarredItem[], key: string, color: StarColor | null): StarredItem[];
+/** The recent items as stored, newest first, each well formed, never more than the cap. */
+export declare function readRecents(profile: unknown): RecentItem[];
+/** The recent items after opening one: it moves to the front, the oldest falls off. */
+export declare function recordRecent(recents: readonly RecentItem[], item: AccountItemRef, nowMs: number): RecentItem[];
+/** The colors the person picked, by workspace id, the valid ones only. */
+export declare function readWorkspaceColors(profile: unknown): Record<string, string>;
+export type WorkspaceColorSource = 'picked' | 'brand' | 'logo' | 'none';
+export interface WorkspaceColor {
+    /** `#RRGGBB`, or null when nothing gives the workspace a color. */
+    color: string | null;
+    source: WorkspaceColorSource;
+    /** Whether the app is tinted with it while you are in the workspace. */
+    tintsApp: boolean;
+}
+/**
+ * A workspace's color: the one the person picked, else the workspace's brand
+ * color (`brandingProfile.primaryColor`), else a color taken from its logo
+ * (Zach, 2026-10-18). The rail tile always shows it; the app is tinted with
+ * it while you are in the workspace unless the person turned "Use each
+ * workspace's brand" off, which stops the brand and logo colors tinting the
+ * app (a picked color still does: the person chose it).
+ */
+export declare function resolveWorkspaceColor(picked: unknown, brandColor: unknown, logoColor: unknown, useWorkspaceBrand: boolean): WorkspaceColor;
+/** The synced theme, every field filled: a missing or unknown value reads as the default. */
+export declare function readAppTheme(profile: unknown): AppThemePrefs;