@longzai-intelligence-layout/preferences 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+/**
+ * 用户偏好编解码器
+ *
+ * 偏好值与存储字符串之间的双向编解码契约与常用构造器，
+ * 解析对键缺失与非法取值一律回落默认形态，对齐既有容错解析惯例
+ */
+/**
+ * 偏好编解码器契约
+ *
+ * @typeParam T - 偏好值类型
+ */
+type PreferenceCodec<T> = {
+  /**
+   * 解析存储原始值为偏好值，键缺失与非法取值回落默认形态
+   */
+  decode: (raw: string | null) => T;
+  /**
+   * 编码偏好值为存储字符串
+   */
+  encode: (value: T) => string;
+  /**
+   * 归敛候选偏好值，越界与非法形态收敛到可用区间，缺省恒等
+   */
+  normalize?: (value: T) => T;
+};
+/**
+ * 归敛候选偏好值
+ *
+ * @typeParam T - 偏好值类型
+ * @param codec - 目标编解码器
+ * @param value - 候选偏好值
+ * @returns 归敛后的偏好值，编解码器未声明归敛时原样返回
+ */
+declare function normalizePreferenceValue<T>(codec: PreferenceCodec<T>, value: T): T;
+/**
+ * 布尔开关编解码器
+ *
+ * @remarks
+ *   存储编码为 `'1'` 与 `'0'`，默认取真时除 `'0'` 外一律解析为真，
+ *   默认取假时仅 `'1'` 解析为真，对齐软换行与折叠类偏好的既有语义
+ * @param defaultValue - 键缺失与非法取值的回落值
+ * @returns 布尔开关编解码器
+ */
+declare function booleanFlagCodec(defaultValue: boolean): PreferenceCodec<boolean>;
+/**
+ * 枚举编解码器
+ *
+ * @remarks
+ *   仅接受值清单内的取值，键缺失与其余取值一律回落默认值
+ * @typeParam V - 枚举取值字面量类型
+ * @param values - 合法取值清单
+ * @param fallback - 键缺失与非法取值的回落值
+ * @returns 枚举编解码器
+ */
+declare function enumCodec<V extends string>(values: readonly V[], fallback: V): PreferenceCodec<V>;
+/**
+ * 钳制数值界
+ */
+type ClampedNumberBounds = {
+  /**
+   * 键缺失与非法取值的回落值
+   */
+  fallback: number;
+  /**
+   * 下界，收敛结果不得低于此值
+   */
+  min: number;
+  /**
+   * 上界，收敛结果不得高于此值
+   */
+  max: number;
+};
+/**
+ * 钳制数值编解码器
+ *
+ * @remarks
+ *   键缺失与非法取值回落默认值，可解析取值钳制到界内并取整
+ * @param bounds - 钳制数值界
+ * @returns 钳制数值编解码器
+ */
+declare function clampedNumberCodec(bounds: ClampedNumberBounds): PreferenceCodec<number>;
+/**
+ * 去空白字符串编解码器
+ *
+ * @remarks
+ *   键缺失与空白取值回落默认值，其余取值去首尾空白后采纳
+ * @param fallback - 键缺失与空白取值的回落值
+ * @returns 去空白字符串编解码器
+ */
+declare function trimmedStringCodec(fallback: string): PreferenceCodec<string>;
+/**
+ * 原样字符串编解码器
+ *
+ * @remarks
+ *   键缺失回落默认值，其余取值原样采纳，适配输入框草稿一类允许任意中间形态的记忆
+ * @param fallback - 键缺失时的回落值
+ * @returns 原样字符串编解码器
+ */
+declare function rawStringCodec(fallback: string): PreferenceCodec<string>;
+/**
+ * 可空字符串编解码器
+ *
+ * @remarks
+ *   null 编码为空串存储，空串与键缺失解析回 null，
+ *   适配仓库标识一类契约上非空字符串的可空记忆
+ * @returns 可空字符串编解码器
+ */
+declare function nullableStringCodec(): PreferenceCodec<string | null>;
+/**
+ * 字符串列表编解码器
+ *
+ * @remarks
+ *   列表以逗号拼接存储，条目自身约定不含逗号，
+ *   解析侧去空串与重复项，键缺失与空白取值回落默认列表
+ * @param fallback - 键缺失与空白取值的回落列表
+ * @returns 字符串列表编解码器
+ */
+declare function stringListCodec(fallback: string[]): PreferenceCodec<string[]>;
+/**
+ * 用户偏好键类型
+ *
+ * 偏好存储键条目与两级存储层级的类型契约，
+ * 键清单由消费方仓自建，键名约定挂消费方命名空间前缀并可枚举供偏好面审计
+ */
+/**
+ * 偏好存储层级
+ */
+type PreferenceTier = 'persistent' | 'session';
+/**
+ * 偏好存储键条目
+ */
+type PreferenceKeyEntry = {
+  /**
+   * 完整存储键名
+   */
+  key: string;
+  /**
+   * 存储层级，`persistent` 跨会话留存在 localStorage，`session` 仅当前标签页留存在 sessionStorage
+   */
+  tier: PreferenceTier;
+};
+/**
+ * 构造带命名空间前缀的偏好存储键名
+ *
+ * @remarks
+ *   消费方键清单内禁止手写拼接字符串，统一经本函数装配保证前缀一致
+ * @param namespace - 消费方命名空间，约定为消费方产品短名
+ * @param name - 偏好短名，使用 kebab-case
+ * @returns 完整存储键名
+ */
+declare function buildPreferenceKey(namespace: string, name: string): string;
+/**
+ * 用户偏好定义
+ *
+ * @typeParam T - 偏好值类型
+ */
+type PreferenceDefinition<T> = {
+  /**
+   * 存储键条目，取自键清单
+   */
+  entry: PreferenceKeyEntry;
+  /**
+   * 编解码器
+   */
+  codec: PreferenceCodec<T>;
+};
+/**
+ * 定义用户偏好
+ *
+ * @typeParam T - 偏好值类型
+ * @param entry - 存储键条目，取自键清单单一真源
+ * @param codec - 编解码器
+ * @returns 用户偏好定义
+ */
+declare function definePreference<T>(entry: PreferenceKeyEntry, codec: PreferenceCodec<T>): PreferenceDefinition<T>;
+/**
+ * 读取偏好值
+ *
+ * @typeParam T - 偏好值类型
+ * @param preference - 用户偏好定义
+ * @returns 解析后的偏好值，键缺失与存储异常回落默认形态
+ */
+declare function readPreference<T>(preference: PreferenceDefinition<T>): T;
+/**
+ * 写入偏好值
+ *
+ * @remarks
+ *   写入前先归敛候选值，存储层异常静默收敛不抛出
+ * @typeParam T - 偏好值类型
+ * @param preference - 用户偏好定义
+ * @param value - 候选偏好值
+ */
+declare function writePreference<T>(preference: PreferenceDefinition<T>, value: T): void;
+/**
+ * 读取偏好存储原始值
+ *
+ * @param tier - 偏好存储层级
+ * @param key - 完整存储键名
+ * @returns 存储原始值，键不存在或存储不可用时为 null
+ */
+declare function readStoredPreference(tier: PreferenceTier, key: string): string | null;
+/**
+ * 写入偏好存储原始值
+ *
+ * @remarks
+ *   存储禁用与配额超限等写入异常不向调用方抛出，写入失败经日志实例告警留痕，
+ *   供偏好未持久化现象的现场定位
+ * @param tier - 偏好存储层级
+ * @param key - 完整存储键名
+ * @param value - 写入的字符串值
+ */
+declare function writeStoredPreference(tier: PreferenceTier, key: string, value: string): void;
+/**
+ * 用户偏好状态集合
+ *
+ * @typeParam T - 偏好值类型
+ */
+type PreferenceControl<T> = {
+  /**
+   * 当前偏好值
+   */
+  value: T;
+  /**
+   * 切换偏好值并记忆到存储
+   *
+   * @param next - 候选偏好值
+   */
+  change: (next: T) => void;
+};
+/**
+ * 用户偏好通用钩子
+ *
+ * @typeParam T - 偏好值类型
+ * @param preference - 用户偏好定义
+ * @returns 偏好值与切换动作
+ */
+declare function usePreference<T>(preference: PreferenceDefinition<T>): PreferenceControl<T>;
+export { type ClampedNumberBounds, type PreferenceCodec, type PreferenceControl, type PreferenceDefinition, type PreferenceKeyEntry, type PreferenceTier, booleanFlagCodec, buildPreferenceKey, clampedNumberCodec, definePreference, enumCodec, normalizePreferenceValue, nullableStringCodec, rawStringCodec, readPreference, readStoredPreference, stringListCodec, trimmedStringCodec, usePreference, writePreference, writeStoredPreference };

package/dist/index.js

@@ -0,0 +1 @@
+import{createBrowserLogger as e}from"@longzai-intelligence-logger/browser";import{useCallback as t,useState as n}from"react";function r(e,t){return e.normalize?e.normalize(t):t}function i(e){return{decode:t=>e?t!==`0`:t===`1`,encode:e=>e?`1`:`0`}}function a(e,t){function n(t){return e.includes(t)}return{decode:e=>e!==null&&n(e)?e:t,encode:e=>e}}function o(e){let t=t=>Math.round(Math.min(Math.max(t,e.min),e.max));return{decode:n=>{if(n===null||n.trim()===``)return e.fallback;let r=Number(n);return Number.isFinite(r)?t(r):e.fallback},encode:e=>String(e),normalize:t}}function s(e){return{decode:t=>t===null||t.trim()===``?e:t.trim(),encode:e=>e}}function c(e){return{decode:t=>t??e,encode:e=>e}}function l(){return{decode:e=>e===null||e===``?null:e,encode:e=>e??``}}function u(e){let t=e=>{let t=e.split(`,`).map(e=>e.trim()).filter(e=>e!==``);return[...new Set(t)]};return{decode:n=>n===null||n.trim()===``?e:t(n),encode:e=>e.join(`,`),normalize:e=>[...new Set(e)]}}const d=e(`lib/preferences/preference-storage.utils`);function f(e){try{return e===`persistent`?window.localStorage:window.sessionStorage}catch{return null}}function p(e,t){try{return f(e)?.getItem(t)??null}catch{return null}}function m(e,t,n){try{f(e)?.setItem(t,n)}catch(e){d.warn(`偏好写入存储失败 ${t}`,{error:e instanceof Error?e.message:String(e)})}}function h(e,t){return{entry:e,codec:t}}function g(e){return e.codec.decode(p(e.entry.tier,e.entry.key))}function _(e,t){let n=r(e.codec,t);m(e.entry.tier,e.entry.key,e.codec.encode(n))}function v(e,t){return`${e}.${t}`}function y(e){let[i,a]=n(()=>g(e));return{value:i,change:t(t=>{let n=r(e.codec,t);a(n),m(e.entry.tier,e.entry.key,e.codec.encode(n))},[e])}}export{i as booleanFlagCodec,v as buildPreferenceKey,o as clampedNumberCodec,h as definePreference,a as enumCodec,r as normalizePreferenceValue,l as nullableStringCodec,c as rawStringCodec,g as readPreference,p as readStoredPreference,u as stringListCodec,s as trimmedStringCodec,y as usePreference,_ as writePreference,m as writeStoredPreference};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@longzai-intelligence-layout/preferences",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Longzai Intelligence 界面偏好键声明与持久化框架包",
+  "keywords": [
+    "layout",
+    "longzai-intelligence",
+    "persistence",
+    "preferences"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "test:unit": "bun test src/__tests__/unit/",
+    "clean": "lzi-dev-cli clean"
+  },
+  "dependencies": {
+    "@longzai-intelligence-logger/browser": "^0.1.8"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.11.2",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.3.0",
+    "happy-dom": "^20.11.2",
+    "react": "19.2.6",
+    "react-dom": "19.2.6"
+  },
+  "peerDependencies": {
+    "react": "^19.2.6"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.