@puresnake/snake-ui 0.0.0-stage → 0.0.2

package/index.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from 'vue';
+
+export * from './types';
+
+/** Snake UI Vue plugin. */
+declare const SnakeUI: Plugin;
+export default SnakeUI;

package/index.scss

@@ -0,0 +1,26 @@
+// 主题 token 单一事实来源(CSS 变量 + SCSS 桥接)
+@import './theme.scss';
+
+// 页面级主题应用(page 基础色 / 暗色选择器 / color-scheme / picker-view 修正)
+@import './libs/css/style.theme.scss';
+
+// 布局与间距工具类(flex / 字号 / 0-80 margin-padding 循环)
+@import './libs/css/common.scss';
+
+// 功能色与文字色工具类
+@import './libs/css/color.scss';
+
+// vue 页面通用工具类(line-clamp / 1px 边框 / safe-area / reset-button)
+/* #ifndef APP-NVUE */
+@import './libs/css/style.vue.scss';
+/* #endif */
+
+// 小程序特有的样式
+/* #ifdef MP */
+@import './libs/css/style.mp.scss';
+/* #endif */
+
+// H5特有的样式
+/* #ifdef H5 */
+@import './libs/css/style.h5.scss';
+/* #endif */

package/index.ts

@@ -0,0 +1,94 @@
+import type { App } from 'vue';
+import { configureRuntime, installUIFoundation, runtimeOptionsKey, snake, type RuntimeOptions } from './libs';
+
+const SnakeUI = {
+    install(app: App, options: RuntimeOptions = {}): void {
+        installUIFoundation(app, options);
+        const configured = configureRuntime(options);
+        app.provide(runtimeOptionsKey, configured);
+        (app.config.globalProperties as Record<string, unknown>).$snake = snake;
+        if (typeof uni !== 'undefined') {
+            (uni as unknown as Record<string, unknown>).$snake = snake;
+        }
+    }
+};
+
+export default SnakeUI;
+
+export type { ImageMode, StyleValue } from './types/global';
+export * from './components/snake-activity-list/types';
+export * from './components/snake-auxiliary-segmentation/types';
+export * from './components/snake-button/types';
+export * from './components/snake-loading/types';
+export * from './components/snake-skeleton/types';
+export * from './components/snake-skeleton-item/types';
+export * from './components/snake-transition/types';
+export * from './components/snake-root-portal/types';
+export * from './components/snake-empty/types';
+export * from './components/snake-icon/types';
+export * from './components/snake-image/types';
+export * from './components/snake-qr-code/types';
+export * from './components/snake-loadmore/types';
+export * from './components/snake-notice-bar/types';
+export * from './components/snake-navbar/types';
+export * from './components/snake-overlay/types';
+export * from './components/snake-tooltip/types';
+export * from './components/snake-popup/types';
+export * from './components/snake-sticky/types';
+export * from './components/snake-swiper/types';
+export * from './components/snake-tabs/types';
+export * from './components/snake-tabbar/types';
+export * from './components/snake-upload/types';
+export * from './components/snake-subsection/types';
+export * from './components/snake-button-sort/types';
+export * from './components/snake-drop-menu/types';
+export * from './components/snake-drop-menu-item/types';
+export * from './components/snake-cell-group/types';
+export * from './components/snake-cell-item/types';
+export * from './components/snake-line/types';
+export * from './components/snake-line-progress/types';
+export * from './components/snake-search/types';
+export * from './components/snake-select/types';
+export * from './components/snake-read-more/types';
+export * from './components/snake-no-network/types';
+export * from './components/snake-link/types';
+export * from './components/snake-text/types';
+export * from './components/snake-calendar/types';
+export * from './components/snake-index-list/types';
+export * from './components/snake-index-list-panel/types';
+export * from './components/snake-index-anchor/types';
+export * from './components/snake-form/types';
+export * from './components/snake-form-item/types';
+export * from './components/snake-input/types';
+export * from './components/snake-textarea/types';
+export * from './components/snake-checkbox/types';
+export * from './components/snake-checkbox-group/types';
+export * from './components/snake-count-down/types';
+export * from './components/snake-radio/types';
+export * from './components/snake-radio-group/types';
+export * from './components/snake-switch/types';
+export * from './components/snake-slider/types';
+export * from './components/snake-cms/types';
+export * from './components/snake-config-provider/types';
+export * from './components/snake-commodity-search/types';
+export * from './components/snake-coupon/types';
+export * from './components/snake-custom-module/types';
+export * from './components/snake-filter-sorts/types';
+export * from './components/snake-follow/types';
+export * from './components/snake-goods-list/types';
+export * from './components/snake-graphic-navigation/types';
+export * from './components/snake-images/types';
+export * from './components/snake-jump-applet/types';
+export * from './components/snake-list-switching/types';
+export * from './components/snake-magic-cube/types';
+export * from './components/snake-modal/types';
+export * from './components/snake-toast/types';
+export * from './components/snake-notice/types';
+export * from './components/snake-page-popup/types';
+export * from './components/snake-picture-ads/types';
+export * from './components/snake-rich-text/types';
+export * from './components/snake-parse/types';
+export * from './components/snake-floating-bubble/types';
+export * from './components/snake-videos/types';
+export * from './libs';
+export * from './locale';

package/libs/cms/blocks.ts

@@ -0,0 +1,103 @@
+export type CmsBlockCategory = 'content' | 'navigation' | 'commerce' | 'custom';
+
+export interface CmsBlockDefinition {
+    version: 1 | 2;
+    category: CmsBlockCategory;
+    componentName: `snake-${string}`;
+    standalone: boolean;
+}
+
+/**
+ * Built-in page-decoration blocks supported by snake-cms.
+ *
+ * Keep this catalog free of Vue imports so it can be consumed by types,
+ * diagnostics and tooling without changing mini-program bundling behavior.
+ */
+export const cmsBlocks = {
+    commoditysearch: {
+        version: 1,
+        category: 'navigation',
+        componentName: 'snake-commodity-search',
+        standalone: true
+    },
+    auxiliarysegmentation: {
+        version: 1,
+        category: 'content',
+        componentName: 'snake-auxiliary-segmentation',
+        standalone: true
+    },
+    richtext: { version: 1, category: 'content', componentName: 'snake-rich-text', standalone: true },
+    graphicnavigation: {
+        version: 1,
+        category: 'navigation',
+        componentName: 'snake-graphic-navigation',
+        standalone: true
+    },
+    images: { version: 1, category: 'content', componentName: 'snake-images', standalone: true },
+    pictureads: { version: 1, category: 'content', componentName: 'snake-picture-ads', standalone: true },
+    magiccube: { version: 1, category: 'content', componentName: 'snake-magic-cube', standalone: true },
+    videos: { version: 1, category: 'content', componentName: 'snake-videos', standalone: true },
+    notice: { version: 1, category: 'content', componentName: 'snake-notice', standalone: true },
+    jumpApplet: { version: 1, category: 'navigation', componentName: 'snake-jump-applet', standalone: true },
+    follow: { version: 1, category: 'navigation', componentName: 'snake-follow', standalone: true },
+    suspension: {
+        version: 1,
+        category: 'navigation',
+        componentName: 'snake-floating-bubble',
+        standalone: true
+    },
+    coupon: { version: 1, category: 'commerce', componentName: 'snake-coupon', standalone: true },
+    pagePopup: { version: 1, category: 'navigation', componentName: 'snake-page-popup', standalone: true },
+    goodslist: { version: 1, category: 'commerce', componentName: 'snake-goods-list', standalone: true },
+    custommodule: { version: 1, category: 'custom', componentName: 'snake-custom-module', standalone: true },
+    'v2.carousel': { version: 2, category: 'content', componentName: 'snake-cms-v2-carousel', standalone: false },
+    'v2.coupon': { version: 2, category: 'commerce', componentName: 'snake-cms-v2-coupon', standalone: false },
+    'v2.custom': { version: 2, category: 'custom', componentName: 'snake-cms-v2-custom', standalone: false },
+    'v2.divider': { version: 2, category: 'content', componentName: 'snake-cms-v2-divider', standalone: false },
+    'v2.floatbutton': {
+        version: 2,
+        category: 'navigation',
+        componentName: 'snake-cms-v2-floatbutton',
+        standalone: false
+    },
+    'v2.goodslist': {
+        version: 2,
+        category: 'commerce',
+        componentName: 'snake-cms-v2-goods-list',
+        standalone: false
+    },
+    'v2.hotzone': { version: 2, category: 'navigation', componentName: 'snake-cms-v2-hotzone', standalone: false },
+    'v2.images': { version: 2, category: 'content', componentName: 'snake-cms-v2-images', standalone: false },
+    'v2.magiccube': {
+        version: 2,
+        category: 'content',
+        componentName: 'snake-cms-v2-magiccube',
+        standalone: false
+    },
+    'v2.notice': { version: 2, category: 'content', componentName: 'snake-cms-v2-notice', standalone: false },
+    'v2.popup': { version: 2, category: 'navigation', componentName: 'snake-cms-v2-popup', standalone: false },
+    'v2.richtext': {
+        version: 2,
+        category: 'content',
+        componentName: 'snake-cms-v2-richtext',
+        standalone: false
+    },
+    'v2.search': { version: 2, category: 'navigation', componentName: 'snake-cms-v2-search', standalone: false },
+    'v2.video': { version: 2, category: 'content', componentName: 'snake-cms-v2-video', standalone: false }
+} as const satisfies Record<string, CmsBlockDefinition>;
+
+export type CmsBuiltinComponent = keyof typeof cmsBlocks;
+export type CmsV1BuiltinComponent = {
+    [Key in CmsBuiltinComponent]: (typeof cmsBlocks)[Key]['version'] extends 1 ? Key : never;
+}[CmsBuiltinComponent];
+export type CmsV2BuiltinComponent = {
+    [Key in CmsBuiltinComponent]: (typeof cmsBlocks)[Key]['version'] extends 2 ? Key : never;
+}[CmsBuiltinComponent];
+
+export const cmsBuiltinComponents = new Set<CmsBuiltinComponent>(
+    Object.keys(cmsBlocks) as CmsBuiltinComponent[]
+);
+
+export function isCmsBuiltinComponent(component: string): component is CmsBuiltinComponent {
+    return cmsBuiltinComponents.has(component as CmsBuiltinComponent);
+}

package/libs/cms/config.ts

@@ -0,0 +1,25 @@
+import { deepMerge } from '../function';
+import type { CmsOptions } from './types';
+
+const DEFAULT_CMS_OPTIONS: CmsOptions = {
+    aliases: { videoss: 'videos' },
+    normalizers: {},
+    services: {},
+    assets: {},
+    cachePrefix: 'snake-ui:cms'
+};
+
+let globalCmsOptions: CmsOptions = deepMerge(DEFAULT_CMS_OPTIONS, {});
+
+export function configureCms(options?: CmsOptions): CmsOptions {
+    globalCmsOptions = deepMerge(globalCmsOptions, options || {});
+    return globalCmsOptions;
+}
+
+export function getCmsOptions(instance?: CmsOptions): CmsOptions {
+    return deepMerge(globalCmsOptions, instance || {});
+}
+
+export function resetCmsOptions(): void {
+    globalCmsOptions = deepMerge(DEFAULT_CMS_OPTIONS, {});
+}

package/libs/cms/index.ts

@@ -0,0 +1,7 @@
+export * from './blocks';
+export * from './types';
+export * from './config';
+export * from './normalize';
+export * from './v2';
+export * from './resolve';
+export * from './use-commerce';

package/libs/cms/normalize.ts

@@ -0,0 +1,135 @@
+import { deepClone } from '../function';
+import { isCmsBuiltinComponent, cmsBlocks } from './blocks';
+export { cmsBuiltinComponents } from './blocks';
+import type {
+    CmsBuiltinComponent,
+    CmsComponentConfig,
+    CmsDiagnostic,
+    CmsNormalizedComponent,
+    CmsOptions,
+    CmsPageInfo
+} from './types';
+import type { CmsV2BuiltinComponent } from './blocks';
+import { normalizeCmsV2Props } from './v2';
+
+export interface CmsNormalizeResult {
+    components: CmsNormalizedComponent[];
+    diagnostics: CmsDiagnostic[];
+}
+
+export function normalizeCmsComponents(
+    input: unknown,
+    pageInfo: CmsPageInfo = {},
+    options: CmsOptions = {}
+): CmsNormalizeResult {
+    const diagnostics: CmsDiagnostic[] = [];
+    const components: CmsNormalizedComponent[] = [];
+    const aliases: Record<string, CmsBuiltinComponent> = { videoss: 'videos', ...(options.aliases || {}) };
+    let hasCommerceSection = false;
+
+    if (!Array.isArray(input)) {
+        diagnostics.push({ code: 'invalid-component', level: 'error', message: 'pageComponents must be an array.' });
+        return { components, diagnostics };
+    }
+
+    input.forEach((raw, index) => {
+        if (!raw || typeof raw !== 'object' || typeof (raw as CmsComponentConfig).component !== 'string') {
+            diagnostics.push({
+                code: 'invalid-component',
+                level: 'error',
+                index,
+                message: 'CMS component must contain a string component key.'
+            });
+            return;
+        }
+
+        let item = deepClone(raw as CmsComponentConfig);
+        const originalComponent = item.component;
+        const normalizer = options.normalizers?.[originalComponent];
+        if (normalizer) {
+            try {
+                const normalized = normalizer(item, { index, pageInfo });
+                if (!normalized) return;
+                item = normalized;
+            } catch (cause) {
+                diagnostics.push({
+                    code: 'normalizer-error',
+                    level: 'error',
+                    index,
+                    component: originalComponent,
+                    message: `Normalizer failed for "${originalComponent}".`,
+                    cause
+                });
+                return;
+            }
+        }
+
+        // alias 只改变实际渲染组件；originalComponent 保留原始下发键，供 normalizer 与诊断追溯来源。
+        const component = aliases[item.component] || item.component;
+        const version = item.component.startsWith('v2.') ? 2 : 1;
+        const setStyle = item.setStyle && typeof item.setStyle === 'object' ? item.setStyle : {};
+        const hasValidV2Props = item.props !== null && typeof item.props === 'object' && !Array.isArray(item.props);
+        let componentProps = hasValidV2Props ? item.props || {} : {};
+        if (version === 1 && (item.visible === false || setStyle.showComponent === false)) return;
+        if (version === 2 && item.active === false) return;
+
+        const builtin = isCmsBuiltinComponent(component);
+        if (version === 2 && !hasValidV2Props) {
+            diagnostics.push({
+                code: 'invalid-component',
+                level: 'error',
+                index,
+                component,
+                message: `CMS v2 component "${component}" must contain an object props field.`
+            });
+        }
+        if (builtin && cmsBlocks[component].version !== version) {
+            diagnostics.push({
+                code: 'invalid-component',
+                level: 'error',
+                index,
+                component,
+                message: `CMS component "${component}" has an invalid protocol version.`
+            });
+        }
+        if (builtin && version === 2 && cmsBlocks[component].version === 2) {
+            componentProps = normalizeCmsV2Props(component as CmsV2BuiltinComponent, componentProps);
+        }
+        if (component === 'goodslist' || component === 'v2.goodslist') {
+            if (hasCommerceSection) {
+                diagnostics.push({
+                    code: 'duplicate-commerce-section',
+                    level: 'warn',
+                    index,
+                    component,
+                    message: 'Only the first goodslist section is rendered.'
+                });
+                return;
+            }
+            hasCommerceSection = true;
+        }
+
+        if (!builtin) {
+            diagnostics.push({
+                code: 'unknown-component',
+                level: 'warn',
+                index,
+                component,
+                message: `Unknown CMS component "${component}".`
+            });
+        }
+
+        components.push({
+            ...item,
+            id: String(item.id ?? `${component}-${index}`),
+            component,
+            version,
+            originalComponent,
+            setStyle,
+            props: componentProps,
+            builtin
+        });
+    });
+
+    return { components, diagnostics };
+}

package/libs/cms/resolve.ts

@@ -0,0 +1,12 @@
+import { isDebugMode } from '../config/state';
+import type { CmsDiagnostic, CmsOptions } from './types';
+import { getCmsOptions } from './config';
+
+export function reportCmsDiagnostic(options: CmsOptions, diagnostic: CmsDiagnostic): void {
+    options.onDiagnostic?.(diagnostic);
+    if (isDebugMode('warn')) console.warn(`[Snake UI CMS] ${diagnostic.message}`, diagnostic);
+}
+
+export function resolveCmsOptions(instance?: CmsOptions): CmsOptions {
+    return getCmsOptions(instance);
+}

package/libs/cms/types.ts

@@ -0,0 +1,164 @@
+import type { CmsBuiltinComponent } from './blocks';
+
+export type {
+    CmsBlockCategory,
+    CmsBlockDefinition,
+    CmsBuiltinComponent,
+    CmsV1BuiltinComponent,
+    CmsV2BuiltinComponent
+} from './blocks';
+
+export interface CmsPageInfo {
+    id?: string | number;
+    pageId?: string | number;
+    name?: string;
+    activityId?: string | number;
+    [key: string]: unknown;
+}
+
+export interface CmsComponentConfig<Style extends Record<string, any> = Record<string, any>> {
+    id?: string | number;
+    component: string;
+    setStyle?: Style;
+    props?: Record<string, any>;
+    active?: boolean;
+    visible?: boolean;
+    [key: string]: unknown;
+}
+
+export interface CmsNormalizedComponent<Style extends Record<string, any> = Record<string, any>> extends Omit<
+    CmsComponentConfig<Style>,
+    'id' | 'setStyle'
+> {
+    id: string;
+    version: 1 | 2;
+    originalComponent: string;
+    setStyle: Style;
+    props: Record<string, any>;
+    builtin: boolean;
+}
+
+export type CmsDiagnosticCode =
+    'invalid-component' | 'unknown-component' | 'normalizer-error' | 'duplicate-commerce-section';
+
+export interface CmsDiagnostic {
+    code: CmsDiagnosticCode;
+    level: 'warn' | 'error';
+    message: string;
+    index?: number;
+    component?: string;
+    cause?: unknown;
+}
+
+export type CmsStatus = 'idle' | 'initial-loading' | 'ready' | 'empty' | 'loading-more' | 'no-more' | 'error';
+
+/** CmsStateChange 类型定义。 */
+export interface CmsStateChange {
+    /** 当前状态。 */
+    status: CmsStatus;
+    /** page 配置。 */
+    page: number;
+    /** item count 配置。 */
+    itemCount: number;
+}
+
+export interface CmsServiceContext {
+    pageInfo: Readonly<CmsPageInfo>;
+    component: Readonly<CmsNormalizedComponent>;
+    generation: number;
+}
+
+export interface CmsActivityResult<Item = Record<string, any>> {
+    items: Item[];
+}
+
+export interface CmsGoodsResult<Item = Record<string, any>> {
+    items: Item[];
+    total?: number;
+    hasMore?: boolean;
+}
+
+export interface CmsCommerceService<
+    Activity = Record<string, any>,
+    Filters = Record<string, any>,
+    Goods = Record<string, any>
+> {
+    getActivities?(
+        context: CmsServiceContext & { params: Record<string, unknown> }
+    ): Promise<CmsActivityResult<Activity>>;
+    getFilters?(context: CmsServiceContext & { params: Record<string, unknown> }): Promise<Filters>;
+    getGoods(context: CmsServiceContext & { params: Record<string, unknown> }): Promise<CmsGoodsResult<Goods>>;
+    navigateGoods?(context: CmsServiceContext & { item: Goods; index: number }): void | Promise<void>;
+}
+
+export interface CmsCouponService {
+    check(context: {
+        config: Record<string, any>;
+        pageInfo?: CmsPageInfo;
+    }): Promise<{ claimable: boolean; message?: string }>;
+    receive(context: {
+        config: Record<string, any>;
+        pageInfo?: CmsPageInfo;
+    }): Promise<{ success: boolean; message?: string }>;
+}
+
+export interface CmsLinkAction {
+    type: 'navigate' | 'mini-program' | 'external' | 'scheme';
+    url?: string;
+    appId?: string;
+    path?: string;
+    extraData?: Record<string, unknown>;
+    envVersion?: 'develop' | 'trial' | 'release';
+    [key: string]: unknown;
+}
+
+export interface CmsLinkService {
+    open(
+        action: CmsLinkAction,
+        context?: { component?: CmsNormalizedComponent; pageInfo?: CmsPageInfo }
+    ): void | Promise<void>;
+    createScheme?(action: CmsLinkAction): Promise<string>;
+}
+
+export interface CmsServices {
+    commerce?: CmsCommerceService;
+    coupon?: CmsCouponService;
+    link?: CmsLinkService;
+}
+
+export interface CmsAssets {
+    backToTop?: string;
+    activityAll?: string;
+    goodsLoading?: string;
+    goodsError?: string;
+    goodsSoldOut?: string;
+    goodsInspection?: string;
+    goodsNewcomer?: string;
+    goodsPopular?: string;
+}
+
+export type CmsNormalizer = (
+    component: CmsComponentConfig,
+    context: { index: number; pageInfo: Readonly<CmsPageInfo> }
+) => CmsComponentConfig | null | undefined;
+
+export interface CmsOptions {
+    aliases?: Record<string, CmsBuiltinComponent>;
+    normalizers?: Record<string, CmsNormalizer>;
+    services?: CmsServices;
+    assets?: CmsAssets;
+    cachePrefix?: string;
+    onDiagnostic?: (diagnostic: CmsDiagnostic) => void;
+}
+
+export class CmsError extends Error {
+    readonly stage: 'normalize' | 'activities' | 'filters' | 'goods' | 'coupon' | 'link';
+    readonly cause?: unknown;
+
+    constructor(stage: CmsError['stage'], message: string, cause?: unknown) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'CmsError';
+        this.stage = stage;
+        this.cause = cause;
+    }
+}