km-card-layout-core 0.1.0

package/interface/elements.ts

@@ -0,0 +1,110 @@
+export type CardElementType =
+  | 'text'
+  | 'image'
+  | 'icon'
+  | 'custom'
+  | 'layout-panel'
+  | 'repeatable-group';
+
+export interface AbsoluteLayoutDefinition {
+  mode: 'absolute';
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  zIndex?: number;
+}
+
+export interface FlexItemOptions {
+  flexGrow?: number;
+  flexShrink?: number;
+  flexBasis?: number | string;
+  order?: number;
+  alignSelf?: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
+}
+
+export interface FlexItemLayoutDefinition {
+  mode: 'flex';
+  item?: FlexItemOptions;
+  width?: number;
+  height?: number;
+}
+
+export type ElementLayout = AbsoluteLayoutDefinition | FlexItemLayoutDefinition;
+
+export interface CardElementBase {
+  id: string;
+  type: CardElementType;
+  layout: ElementLayout;
+  visible?: boolean;
+  binding?: string;
+  style?: Record<string, string | number | undefined>;
+  defaultValue?: string;
+}
+
+export interface TextElement extends CardElementBase {
+  type: 'text';
+  align?: 'left' | 'center' | 'right';
+  multiline?: boolean;
+}
+
+export interface ImageElement extends CardElementBase {
+  type: 'image';
+  alt?: string;
+  fit?: 'cover' | 'contain';
+  defaultUrl?: string;
+}
+
+export interface IconElement extends CardElementBase {
+  type: 'icon';
+  name?: string;
+}
+
+export interface CustomElement extends CardElementBase {
+  type: 'custom';
+}
+
+export interface LayoutPanelElement extends CardElementBase {
+  type: 'layout-panel';
+  container: {
+    mode: 'absolute' | 'flex';
+    options?: {
+      direction?: 'row' | 'column';
+      wrap?: 'nowrap' | 'wrap';
+      justifyContent?:
+        | 'flex-start'
+        | 'flex-end'
+        | 'center'
+        | 'space-between'
+        | 'space-around'
+        | 'space-evenly';
+      alignItems?: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
+      gap?: number | { row: number; column: number };
+      padding?: number | [number, number] | [number, number, number, number];
+    };
+  };
+  children?: CardElement[];
+}
+
+export interface RepeatableGroupItem {
+  id: string;
+  elements: CardElement[];
+  data?: Record<string, any>;
+}
+
+export interface RepeatableGroupElement extends CardElementBase {
+  type: 'repeatable-group';
+  dataPath: string;
+  itemTemplate: CardElement[];
+  items: RepeatableGroupItem[];
+  maxItems?: number;
+  mutualExcludes?: string[];
+}
+
+export type CardElement =
+  | TextElement
+  | ImageElement
+  | IconElement
+  | CustomElement
+  | LayoutPanelElement
+  | RepeatableGroupElement;

package/interface/index.ts

@@ -0,0 +1,3 @@
+export * from './elements';
+export * from './layout';
+export * from './render';

package/interface/layout.ts

@@ -0,0 +1,19 @@
+import type { CardElement } from './elements';
+
+export interface CardLayoutSchema {
+  name?: string;
+  container: {
+    mode: 'absolute';
+  };
+  width: number;
+  height: number;
+  backgroundImage?: string;
+  backgroundZIndex?: number;
+  fontColor?: string;
+  borderRadius?: number;
+  padding?: number;
+  children: CardElement[];
+  thumbnail?: string;
+}
+
+export type CardLayoutInput = CardLayoutSchema[];

package/interface/render.ts

@@ -0,0 +1,42 @@
+import type { CardElementType, CardElement } from './elements';
+import type { CardLayoutInput, CardLayoutSchema } from './layout';
+
+export interface RenderNode {
+  id: string;
+  type: CardElementType | 'text';
+  wrapperStyle: string;
+  contentStyle: string;
+  name?: string;
+  text?: string;
+  src?: string;
+  mode?: string;
+  children?: RenderNode[];
+  visible?: boolean;
+}
+
+export interface RenderPageResult {
+  renderTree: RenderNode[];
+  cardStyle: string;
+  backgroundImage: string;
+  backgroundStyle: string;
+}
+
+export type RenderResult = RenderPageResult[];
+
+export interface BindingContext {
+  /**
+   * 当前上下文数据的绑定前缀（repeatable-group 内为 dataPath）
+   */
+  contextBinding?: string;
+  /**
+   * 当前上下文数据（repeatable-group 单条数据）
+   */
+  contextData?: any;
+}
+
+export type {
+  CardElement,
+  CardElementType,
+  CardLayoutInput,
+  CardLayoutSchema,
+};

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "km-card-layout-core",
+  "version": "0.1.0",
+  "description": "Shared render helpers for CardMaster layout JSON (binding resolution, repeatable groups, layout normalization).",
+  "main": "index.js",
+  "types": "types.d.ts",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "release": "pnpm run build && npm publish --access public"
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": false,
+    "outDir": "./dist",
+    "rootDir": "./",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "target": "ES2019",
+    "allowImportingTsExtensions": false
+  },
+  "include": ["./**/*.ts"],
+  "exclude": ["./dist", "./node_modules"]
+}

package/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Declaration file for km-card-layout-core.
+ * Mirrors the exported types/functions from index.ts.
+ */
+
+export * from './interface';
+
+import type {
+  BindingContext,
+  CardElement,
+  CardLayoutInput,
+  CardLayoutSchema,
+  RenderNode,
+  RenderResult,
+} from './interface';
+
+export function addUnit(
+  value: string | number | undefined | null,
+  unit: 'px' | 'rpx'
+): string | undefined;
+
+export function styleObjectToString(
+  style?: Record<string, any>,
+  unit?: 'px' | 'rpx'
+): string;
+
+export function normalizeLayout(layout: CardLayoutInput): CardLayoutSchema[];
+
+export function resolveBindingValue(
+  binding: string | undefined,
+  rootData: Record<string, any>,
+  context?: BindingContext
+): any;
+
+export function buildRenderNodes(
+  children: CardElement[],
+  data: Record<string, any>,
+  unit?: 'px' | 'rpx',
+  context?: BindingContext
+): RenderNode[];
+
+export function buildRenderResult(
+  layout: CardLayoutInput,
+  data: Record<string, any>,
+  unit?: 'px' | 'rpx'
+): RenderResult;

package/utils.ts

@@ -0,0 +1,67 @@
+import type { CardElement, CardLayoutSchema } from './interface';
+import { TemplateBackground } from './interface/data/payload';
+
+export function backgroundChange(
+  bg: TemplateBackground,
+  layout: CardLayoutSchema
+): CardLayoutSchema {
+  const toNameArray = (name?: string | string[]) => {
+    if (Array.isArray(name)) return name.filter(Boolean);
+    if (!name) return [];
+    return `${name}`
+      .split(',')
+      .map(n => n.trim())
+      .filter(Boolean);
+  };
+
+  const applySpecialColor = (el: CardElement): CardElement => {
+    const extras = bg.fontColorExtra || [];
+    if (!extras.length) return el;
+
+    const keys: string[] = [];
+    if (el.binding) keys.push(String(el.binding));
+    if (el.id) keys.push(String(el.id));
+    if (el.type === 'icon') keys.push('icon');
+    if (el.type === 'custom') keys.push('decor');
+
+    const matched = extras.find(sc =>
+      toNameArray(sc.name).some(n => keys.some(k => k?.startsWith(n)))
+    );
+    if (!matched) return el;
+
+    const baseStyle = { ...(el.style || {}) };
+    if (el.type === 'custom') {
+      return { ...el, style: { ...baseStyle, backgroundColor: matched.color } };
+    }
+    return { ...el, style: { ...baseStyle, color: matched.color } };
+  };
+
+  const traverse = (children: CardElement[] = []): CardElement[] =>
+    children.map(el => {
+      if (!el) return el;
+      if (el.type === 'layout-panel') {
+        return {
+          ...el,
+          children: traverse(el.children || []),
+        };
+      }
+      if (el.type === 'repeatable-group') {
+        return {
+          ...el,
+          itemTemplate: traverse(el.itemTemplate || []),
+          items: (el.items || []).map(item => ({
+            ...item,
+            elements: traverse(item.elements || []),
+          })),
+        };
+      }
+      return applySpecialColor(el);
+    });
+
+  return {
+    ...layout,
+    backgroundImage: bg.imgUrl,
+    fontColor: bg.fontColor || layout.fontColor,
+    children: traverse(layout.children || []),
+  };
+}