jsbox-cview 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gandum2077
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# JSBox-CView
+
+为 JSBox 设计的微型框架。CView 主要实现 MVC 架构中 View、Controller 两部分。
+
+CView 的含义是“组件化视图”。设计目的是：
+
+- 通过组件化的方式，将 JSBox view 的定义和实例绑定，简化使用
+- 方便地创建自定义组件
+
+## View
+
+CView 的视图组件是非侵入式的。换言之，你可以全部使用 CView 开发，也可以只使用你喜欢的某一个组件或方法。
+
+它实现了 JSBox 原本的视图组件，同时增加了一些新的自定义组件。通过继承和组合，还可以创建更多的自定义组件。
+
+## Controller
+
+View 组件是收敛的，而 Controller 负责页面的构成和更新。
+它可以实现一些常用的页面构建形式，比如底部 Tab 分页，左侧滑动分页，弹出式页面等。

package/components/alert/input-alert.ts

@@ -0,0 +1,73 @@
+/**
+ * # CView InputAlert
+ * 
+ * 显示一个输入框提示
+ */
+
+import {
+  UIAlertActionStyle,
+  UIAlertControllerStyle,
+  UIAlertAction,
+  UIAlertController
+} from "./uialert";
+
+import { l10n } from "../../utils/l10n";
+
+export function inputAlert({
+  title = "",
+  message = "",
+  text = "",
+  placeholder,
+  type = 0,
+  secure = false,
+  cancelText = l10n("CANCEL"),
+  confirmText = l10n("OK")
+}: {
+  title?: string;
+  message?: string;
+  text?: string;
+  placeholder?: string;
+  type?: number;
+  secure?: boolean;
+  cancelText?: string;
+  confirmText?: string;
+}): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const alertVC = new UIAlertController(
+      title,
+      message,
+      UIAlertControllerStyle.Alert
+    );
+    alertVC.addTextField({
+      placeholder,
+      text,
+      type,
+      secure,
+      events: {
+        shouldReturn: () => {
+          const input = alertVC.getText(0);
+          const isValid = input.length > 0;
+          return isValid;
+        }
+      }
+    });
+
+    alertVC.addAction(
+      new UIAlertAction(cancelText, UIAlertActionStyle.Destructive, cancelEvent)
+    );
+    alertVC.addAction(
+      new UIAlertAction(confirmText, UIAlertActionStyle.Default, confirmEvent)
+    );
+    alertVC.present();
+
+    function confirmEvent() {
+      const input: string = alertVC.getText(0);
+      resolve(input);
+    }
+    function cancelEvent() {
+      reject("cancel");
+    }
+  });
+}
+
+

package/components/alert/login-alert.ts

@@ -0,0 +1,75 @@
+/**
+ * # CView LoginAlert
+ * 
+ * 显示一个登录输入框提示
+ */
+
+import {
+  UIAlertActionStyle,
+  UIAlertControllerStyle,
+  UIAlertAction,
+  UIAlertController
+} from "./uialert";
+
+import { l10n } from "../../utils/l10n";
+
+export function loginAlert({
+  title = "",
+  message = "",
+  placeholder1 = "",
+  placeholder2 = "",
+  cancelText = l10n("CANCEL"),
+  confirmText = l10n("OK")
+}: {
+  title?: string;
+  message?: string;
+  placeholder1?: string;
+  placeholder2?: string;
+  cancelText?: string;
+  confirmText?: string;
+  } = {}): Promise<{ username: string; password: string }> {
+  return new Promise((resolve, reject) => {
+    const alertVC = new UIAlertController(
+      title,
+      message,
+      UIAlertControllerStyle.Alert
+    );
+
+    alertVC.addTextField({
+      placeholder: placeholder1
+    });
+
+    alertVC.addTextField({
+      placeholder: placeholder2,
+      secure: true,
+      events: {
+        shouldReturn: () => {
+          const username = alertVC.getText(0);
+          const password = alertVC.getText(1);
+          const isValid = username.length > 0 && password.length > 0;
+          return isValid;
+        }
+      }
+    });
+
+    alertVC.addAction(
+      new UIAlertAction(cancelText, UIAlertActionStyle.Destructive, cancelEvent)
+    );
+    alertVC.addAction(
+      new UIAlertAction(confirmText, UIAlertActionStyle.Default, confirmEvent)
+    );
+    alertVC.present();
+
+    function confirmEvent() {
+      const username = alertVC.getText(0);
+      const password = alertVC.getText(1);
+      resolve({
+        username,
+        password
+      });
+    }
+    function cancelEvent() {
+      reject("cancel");
+    }
+  });
+}

package/components/alert/plain-alert.ts

@@ -0,0 +1,49 @@
+/**
+ * # CView PlainAlert
+ * 
+ * 显示一个文字提示
+ */
+
+import {
+  UIAlertActionStyle,
+  UIAlertControllerStyle,
+  UIAlertAction,
+  UIAlertController
+} from "./uialert";
+
+import { l10n } from "../../utils/l10n";
+
+export function plainAlert({
+  title = "",
+  message = "",
+  cancelText = l10n("CANCEL"),
+  confirmText = l10n("OK")
+}: {
+  title?: string;
+  message?: string;
+  cancelText?: string;
+  confirmText?: string;
+} = {}): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const alertVC = new UIAlertController(
+      title,
+      message,
+      UIAlertControllerStyle.Alert
+    );
+
+    alertVC.addAction(
+      new UIAlertAction(cancelText, UIAlertActionStyle.Destructive, cancelEvent)
+    );
+    alertVC.addAction(
+      new UIAlertAction(confirmText, UIAlertActionStyle.Default, confirmEvent)
+    );
+    alertVC.present();
+
+    function confirmEvent() {
+      resolve("ok");
+    }
+    function cancelEvent() {
+      reject("cancel");
+    }
+  });
+}

package/components/alert/uialert.ts

@@ -0,0 +1,110 @@
+/**
+ * Alert的基础类
+ */
+
+export const UIAlertActionStyle = {
+  Default: 0,
+  Cancel: 1,
+  Destructive: 2
+};
+
+export const UIAlertControllerStyle = {
+  ActionSheet: 0,
+  Alert: 1
+};
+
+export class UIAlertAction {
+  title: string;
+  style: number;
+  instance: any;
+
+  constructor(title: string, style = UIAlertActionStyle.Default, handler: Function) {
+    this.title = title;
+    this.style = style;
+    this.instance = $objc("UIAlertAction").$actionWithTitle_style_handler(
+      title,
+      style,
+      $block("void, UIAlertAction *", () => {
+        if (handler) {
+          handler(this);
+        }
+      })
+    );
+  }
+}
+
+export class UIAlertController {
+  title: string;
+  message: string;
+  style: number;
+  instance: any;
+  constructor(title: string, message: string, style = UIAlertControllerStyle.ActionSheet) {
+    this.title = title;
+    this.message = message;
+    this.style = style;
+    this.instance = $objc(
+      "UIAlertController"
+    ).$alertControllerWithTitle_message_preferredStyle(title, message, style);
+  }
+
+  addAction(action: UIAlertAction) {
+    this.instance.$addAction(action.instance);
+  }
+
+  addTextField(options: any) {
+    this.instance.$addTextFieldWithConfigurationHandler(
+      $block("void, UITextField *", (textField: any) => {
+        textField.$setClearButtonMode(1);
+
+        if (options.type) {
+          textField.$setKeyboardType(options.type);
+        }
+        if (options.placeholder) {
+          textField.$setPlaceholder(options.placeholder);
+        }
+        if (options.text) {
+          textField.$setText(options.text);
+        }
+        if (options.textColor) {
+          textField.$setTextColor(options.textColor.ocValue());
+        }
+        if (options.font) {
+          textField.$setFont(options.font.ocValue());
+        }
+        if (options.align) {
+          textField.$setTextAlignment(options.align);
+        }
+        if (options.secure) {
+          textField.$setSecureTextEntry(true);
+        }
+        if (options.events) {
+          const events = options.events;
+          textField.$setDelegate(
+            $delegate({
+              type: "UITextFieldDelegate",
+              events: {
+                "textFieldShouldReturn:": (textField: any) => {
+                  if (events.shouldReturn) {
+                    return events.shouldReturn();
+                  } else {
+                    return true;
+                  }
+                }
+              }
+            })
+          );
+        }
+      })
+    );
+  }
+
+  getText(index: number) {
+    const textField = this.instance.$textFields().$objectAtIndex(index);
+    const text = textField.$text();
+    return text.jsValue();
+  }
+
+  present() {
+    this.instance.$show();
+  }
+}

package/components/artificial-flowlayout.ts

@@ -0,0 +1,321 @@
+/** 
+ * # cview ArtificialFlowlayout
+ * 
+ * 仿制的 flowlayout  
+ * 通过在右侧插入空白的 item，从而作出假象的左对齐。
+ * 
+ * 已知问题：
+ * 
+ * - 当某一行中所占用的总宽度恰好使得右侧的剩余宽度在 1 spacing 到 2 spacing 之间，此时无法插入空白 item，这一行的 spacing 将会被拉宽
+ * - 不可以依赖 indexPath，请将原数据和此 CView 的数据分离，通过 data 中加入标记的方法来定位的原数据
+ * 
+ * !!! layout 当中必须有关于 height 的约束 ！！！
+ * 
+ * - columns 不定，item 宽度不相等但高度固定，spacing 固定，左对齐，自动换行
+ * - 不可滚动，会自动调整自身的高度，因而拥有方法 heightToWidth(width: number): number 用于事前确定其应有的高度
+ *   事件 heightChanged: (cview, height) => void 用于高度变更时回调
+ * - 此控件不能直接指定 props.data，而是需要指定 sections，并且每个 item 都需要改为{data: any, width: number} 其中 data 代表原 item 的内容，width 代表其应有的宽度
+ * - 如果 item.width > frame.width - 2 spacing, 那么生成的对应 item 将单独占用一行，其宽度为 frame.width - 2 spacing
+ * -
+ * 
+ * 特别参数
+ * 
+ * - sections: {title: string, items: {data: any, width: number}[]}[] 即使只有单个 section 也必须用多 sections 的写法
+ *   此参数可以在 cview.view 生成后重新写入
+ * 
+ * props:
+ * 
+ * - itemHeight 默认为 40
+ * - spacing 默认为 5
+ * - scrollEnabled 固定为 false
+ * 
+ * 除了 props: data 和 events: itemSize 不可用，其他均和 matrix 一致
+ * 
+ * methods
+ * 
+ * - heightToWidth(width: number): number
+ * - getSectionHeights(width: number): number[]
+ * - reload()
+ */
+
+import { Base } from "./base";
+import { Matrix } from "./single-views";
+import { cvid } from "../utils/cvid";
+
+interface FlowlayoutSection {
+  title?: string;
+  items: {
+    data: { [key: string]: any };
+    width: number;
+  }[];
+}
+
+interface InnerSection {
+  title?: string;
+  items: {
+    data: { [key: string]: any };
+    width: number;
+    blank: boolean;
+    realIndex: number;
+  }[];
+}
+
+export class ArtificialFlowlayout extends Base<UIView, UiTypes.ViewOptions> {
+  private _sections: FlowlayoutSection[]; // 原数据，不变动，不包含空白占位的item
+  private _innerSections: InnerSection[]; // 带空白占位的item
+  private _props: UiTypes.MatrixProps;
+  private _cellRootViewId: string;
+  private _width: number;
+  private _height: number;
+  private _matrix: Matrix;
+  _defineView: () => UiTypes.ViewOptions;
+
+  /**
+   * 创建一个人工流式布局实例。
+   * @param sections - 此控件不能直接指定 props.data，而是需要指定 sections，
+   * 并且每个 item 都需要改为{data: any, width: number} 其中 data 代表原 item 的内容，width 代表其应有的宽度
+   * @param props - 矩阵的属性。不可指定columns，可以指定spacing，itemHeight，template。scrollEnabled固定为false。
+   * @param layout - 视图的布局函数。
+   * @param events - 事件处理程序的对象。
+   * - didSelect: (cview, indexPath, data): void - 其中indexPath是原sections的indexPath，data是原item的内容。
+   * - didLongPress: (cview, indexPath, data): void
+   * - heightChanged: (cview, height): void
+   * 
+   * @method set sections - 设置 sections。
+   * @method get sections - 获取 sections。
+   * @method heightToWidth - 根据宽度计算高度.
+   * 
+   */
+  constructor({ sections, props, layout, events }: {
+    sections: FlowlayoutSection[];
+    props: UiTypes.MatrixProps;
+    layout: (make: MASConstraintMaker, view: UIView) => void;
+    events: {
+      didSelect?: (sender: ArtificialFlowlayout, indexPath: NSIndexPath, data: object) => void;
+      didLongPress?: (sender: ArtificialFlowlayout, indexPath: NSIndexPath, data: object) => void;
+      heightChanged?: (sender: ArtificialFlowlayout, height: number) => void;
+    }
+  }) {
+    super();
+    this._sections = sections;
+    this._innerSections = []
+    this._props = {
+      spacing: 5,
+      itemHeight: 40,
+      ...props,
+      scrollEnabled: false,
+      columns: undefined
+    };
+    this._cellRootViewId = cvid.newId;
+    this._width = 300;
+    this._height = 0;
+    this._props.template = this._addCellIdForTemplate(this._props.template);
+    this._matrix = new Matrix({
+      props: {
+        ...this._props,
+        itemHeight: undefined
+      },
+      layout: $layout.fill,
+      events: {
+        itemSize: (sender, indexPath) => {
+          const item = this._innerSections[indexPath.section].items[indexPath.item];
+          return $size(Math.max(item.width, 0), this._props.itemHeight || 40);
+        },
+        didSelect: (sender, indexPath, data) => {
+          const item = this._innerSections[indexPath.section].items[indexPath.item];
+          if (item.blank) return;
+          const realIndexPath = $indexPath(indexPath.section, item.realIndex);
+          if (events.didSelect) events.didSelect(this, realIndexPath, data);
+        },
+        didLongPress: (sender, indexPath, data) => {
+          const item = this._innerSections[indexPath.section].items[indexPath.item];
+          if (item.blank) return;
+          const realIndexPath = $indexPath(indexPath.section, item.realIndex);
+          if (events.didSelect) events.didSelect(this, realIndexPath, data);
+        }
+      }
+    })
+    this._defineView = () => {
+      return {
+        type: "view",
+        props: {
+          id: this.id
+        },
+        layout: layout,
+        events: {
+          layoutSubviews: sender => {
+            sender.relayout();
+            this._width = sender.frame.width;
+            this._innerSections = this._addBlankItem(this._sections, this._width, this._props.spacing || 5);
+            const height = this._calculateSectionsHeight(
+              this._innerSections,
+              this._width,
+              this._props.spacing || 5,
+              this._props.itemHeight || 40
+            );
+            this.view.updateLayout((make, view) => make.height.equalTo(height));
+            this._props.data = this._innerSections.map(n => ({
+              title: n.title,
+              items: n.items.map(n => n.data)
+            }));
+            this._matrix.view.data = this._props.data;
+            if (height !== this._height && events.heightChanged) events.heightChanged(this, height);
+            this._height = height;
+          }
+        },
+        views: [this._matrix.definition]
+      };
+    }
+  }
+
+  set sections(sections) {
+    this._sections = sections;
+    this._innerSections = this._addBlankItem(this._sections, this._width, this._props.spacing || 5);
+    this._props.data = this._innerSections.map(n => ({
+      title: n.title,
+      items: n.items.map(n => n.data)
+    }));
+    this._matrix.view.data = this._props.data;
+  }
+
+  get sections() {
+    return this._sections;
+  }
+
+  /**
+   * 为每个 section 的 items 添加空白占位的 item。
+   * @param sections - 原始数据的数组，每个元素包含一个标题和一组项目。
+   * @param containerWidth - 容器的宽度。
+   * @param spacing - 项目之间的间距。
+   * @returns 带有空白占位的 item 的数组。
+   */
+  protected _addBlankItem(sections: FlowlayoutSection[], containerWidth: number, spacing: number): InnerSection[] {
+    return sections.map((section) => {
+      let lineWidth = spacing  // 当前行已使用的宽度
+      const newItems: {
+        data: { [key: string]: any };
+        width: number;
+        blank: boolean;
+        realIndex: number;
+      }[] = []
+      let index = 0
+      for (const item of section.items) {
+        const itemWidthWithSpacing = item.width + spacing
+        // 检查是否需要换行：当前行宽度 + 项目宽度 + 间距 > 容器宽度
+        if (lineWidth + itemWidthWithSpacing > containerWidth && lineWidth > spacing) {
+          // 插入空白项目填充剩余宽度
+          const blankWidth = containerWidth - lineWidth + spacing  // 计算空白项目宽度
+          if (blankWidth > 0) { // 防止插入宽度为负的空白项目
+            const blankItemData: {[key: string]: any} = {}
+            blankItemData[this._cellRootViewId] = { hidden: true }
+            newItems.push({
+              data: blankItemData,
+              width: blankWidth,
+              blank: true,
+              realIndex: -1
+            })
+            // 然后换行，重置lineWidth
+            lineWidth = spacing + itemWidthWithSpacing
+            newItems.push({
+              data: item.data,
+              width: item.width,
+              blank: false,
+              realIndex: index
+            })
+          } else { // 当剩余宽度恰好大于spacing但不超过2倍spacing时，需要直接换行，但这行的spacing会被稍微拉长
+            // 直接换行，重置lineWidth
+            lineWidth = spacing + itemWidthWithSpacing
+            newItems.push({
+              data: item.data,
+              width: item.width,
+              blank: false,
+              realIndex: index
+            })
+          }
+        } else {
+          newItems.push({
+            data: item.data,
+            width: item.width,
+            blank: false,
+            realIndex: index
+          })
+          lineWidth += itemWidthWithSpacing
+        }
+        index++;
+      }
+      return {
+        title: section.title,
+        items: newItems,
+      };
+    });
+  }
+
+  /**
+   * 计算 sections 的高度。
+   * @param sections - 带有空白占位的 item 的数组。
+   * @param containerWidth - 容器的宽度。
+   * @param spacing - 项目之间的间距。
+   * @param itemHeight - 项目的高度。
+   * @returns 计算得到的高度值。
+   */
+  protected _calculateSectionsHeight(
+    sections: InnerSection[],
+    containerWidth: number,
+    spacing: number,
+    itemHeight: number
+  ): number {
+    let height = spacing  // 当前行已使用的高度
+    const lineHeight = itemHeight + spacing // 每行的高度，包括项目高度和间距
+    for (const section of sections) {
+      let lineWidth = 0  // 当前行已使用的宽度
+      for (const item of section.items) {
+        const itemWidthWithSpacing = item.width + spacing
+        // 检查是否需要换行：当前行宽度 + 项目宽度 + 间距 > 容器宽度
+        if (lineWidth + itemWidthWithSpacing > containerWidth && lineWidth > spacing) {
+          // 换行，重置lineWidth
+          lineWidth = spacing + itemWidthWithSpacing
+          height += lineHeight
+        } else {
+          lineWidth += itemWidthWithSpacing
+        }
+      }
+    }
+    return height
+  }
+
+  private _addCellIdForTemplate(template: {
+    views: UiTypes.AllViewOptions[];
+    props?: UiTypes.BaseViewProps
+  }): {
+    props: UiTypes.BaseViewProps;
+    views: UiTypes.AllViewOptions[];
+  } {
+    if (!template || typeof template !== "object") throw new Error("Invalid template");
+    const topProps = template.props;
+    if (topProps && topProps.id) delete topProps.id;
+    return {
+      props: {},
+      views: [
+        {
+          type: "view",
+          props: {
+            ...topProps,
+            id: this._cellRootViewId
+          },
+          layout: $layout.fill,
+          views: template.views
+        }
+      ]
+    };
+  }
+
+  /**
+   * 根据宽度计算高度。
+   * @param width - 宽度值。
+   * @returns 计算得到的高度值。
+   */
+  heightToWidth(width: number) {
+    const innerSections = this._addBlankItem(this._sections, width, this._props.spacing || 5);
+    return this._calculateSectionsHeight(innerSections, width, this._props.spacing || 5, this._props.itemHeight || 40);
+  }
+}