anguless-com/angulux

# angulux **一个精选的 Angular 22 UI 组件库，fork 自 PrimeNG (21.1.9) 的最后一个 MIT 版本，其 MIT 来源由机器证明，而非在文字中宣称。** [](https://github.com/anguless-com/angulux/actions/workflows/ci.yml) [](LICENSE) [](https://www.npmjs.com/package/angulux) [](https://scorecard.dev/viewer/?uri=github.com/anguless-com/angulux) ``` npm install @anguless/angulux @primeuix/themes ``` ``` import { provideAngulux } from '@anguless/angulux/config'; import Aura from '@primeuix/themes/aura'; bootstrapApplication(App, { providers: [provideAngulux({ theme: { preset: Aura } })] }); ``` **为什么需要第二个包。** angulux 本身不附带任何主题预设，因此预设来自于 `@primeuix/themes` —— PrimeTek 的包，并且在 `2.0.3` 版本之前都是 MIT 协议。angulux 本身在安装时，其依赖树中包含 **零个 PrimeTek 包**；去掉第二个包， `provideAngulux()` 将以无样式运行，但依然能够正常工作。 它被声明为版本范围为 `^2.0.0` 的**可选** peer dependency，并且这个版本上限是刻意的： `3.0.0` 是第一个商业版本。你需要清楚这能为你带来什么—— peer dependency 的范围只是 一个*警告*，而不是锁定。`npm install @primeuix/themes@3` 依然会执行成功；它只会打印出一个 `ERESOLVE` 警告，指出它破坏了哪个版本范围。这对于实际发生的常见情况（一次常规的 `npm update`，或者某个代理程序升级依赖时，悄无声息地跨越了许可证 边界）来说已经足够了，但对于其他情况则无能为力。如果你非常在意这个边界， 请精确锁定版本，并在你自己的构建中运行许可证守卫。这个守卫已经作为一个 独立的 MIT 包发布，即 [`angulux-license-guard`](packages/angulux-license-guard) ——它会读取你的 lockfile，对于任何无法验证的 PrimeTek 包都会直接报错中断，并且它本身没有任何 依赖。它可以在任何项目中运行；它不要求必须使用 angulux。 ## 请先阅读本部分 angulux **不是** PrimeNG 的直接替代品，它也**不想**成为 社区的延续版本。以下三个事实决定了你是否应该继续往下读： 1. **它仅发布了 PrimeNG 117 个模块中的 64 个。** Editor、Tree、OrganizationChart、PickList、 OrderList、Listbox 以及其他 47 个模块均未被移植——所有这 53 个模块都列在 [`packages/angulux/attic/`](packages/angulux/attic/) 中。请参阅 [angulux 不是什么](#what-angulux-is-not)。 2. **选择器已被重命名。** `p-button` 变成了 `agl-button`，`pTooltip` 变成了 `aglTooltip`。 CSS 类名（`p-*`）被刻意保留了——原因请参阅 [NOTICE](NOTICE)。 3. **巴士因子（Bus factor）为 1。** 只有一名维护者，每年需承担维护两个 Angular 大版本更新的永久义务。MIT 协议，尽力而为，**没有 SLA**。如果这对你来说是不可接受的条件，那它确实不适合你。 如果你需要的是“我正在使用 PrimeNG 21，并且我希望以最小的改动继续使用它”，那么 最坦白的回答是 [Optimus UI](https://github.com/openng-org/optimus-ui) 比起 angulux 更适合 你：它保留了 `p-*` 选择器并且包含了完整的模块集合。 我们宁愿在这里坦诚地告诉你，也不愿以后再去处理关于这个问题的 issue。 ## angulux 为什么存在 PrimeNG 22 转向了商业许可协议。包括 **21.1.9** 在内的之前的每个版本 都是在 MIT 协议下发布的，并且将永久保持 MIT 协议——这就是已发布的许可授权 的含义。angulux 正是在这个边界处产生的 fork，专为那些痛点在于**控制权和 法律确定性**，而不是价格的团队而生。 有趣的部分并不在于这个 fork。而在于这个边界是由机器来强制执行的。 ## 三个真正与众不同的地方 ### 1. 每一个版本都由机器证明为 MIT 协议 每次提交和每个 pull request 都会运行七道关卡。它们不检查代码风格——每一道关卡 都能杜绝一类在本代码仓库中曾经发生过的失败情况。 | 关卡 | 拒绝让其通过的内容 | |---|---| | `check:catalog` | 依赖版本偏离了锁定的目录 | | `check:scope` | 传递性闭包偏离了 64 个受保障的模块 | | `check:license` | 任何来自 MIT 协议之后发布的 PrimeTek 包进入依赖树 | | `check:names` | PrimeNG 的名称存留在选择器、API 或**商标**位置——包括在纯字符串、JSDoc 链接和 DOM 属性中 | | `check:risk-coverage` | 浏览器测试关卡的范围偏离了从源码计算出的高风险装饰器 | | `check:language` | 非英文文本进入公开仓库 | | `check:public-tree` | 仅供内部使用的路径留在了 git 索引中（`.gitignore` 并**不会**取消跟踪） | ``` npm run check # all seven, ~3 seconds ``` 第八道关卡 `check:publishable` 在构建之后运行，而不是在测试套件中：它会 打包每个包，并从 tarball 中读取回 `package.json`，因此被检查的内容正是 npm 将要接收的确切字节。它之所以存在，是因为曾经有一个读取 源码树的守卫在测试通过时，实际上有三个包正准备发布一个 无法安装的 `workspace:` 依赖。 七道关卡中的两道——`check:license` 和 `check:catalog`——**也会按计划每天运行**， 这并不是冗余。Pull request 运行只能证明代码树在*我们最后一次提交时*是干净的， 而这两道关卡所强制执行的边界却存在于本仓库之外：PrimeTek 决定他们哪一个版本是最后的 MIT 版本，而这可能在我们这里没有任何人 推送代码的某一天发生变化。另外五道关卡守卫的是我们自己的代码，因此只有在提交的那一瞬间它们才可能出错。 除此之外：`provenance/manifest.json` 记录了每个已归档 MIT 工件的 SHA-256 校验和和注册表发布 时间戳，并且浏览器测试关卡会在真实的 Chromium 中渲染 **15 个（全部 15 个）** 被标记为高风险的装饰器，并对结果进行断言——因为一个绿色的 类型检查无法发现渲染 bug。 当前证据，可通过干净的 checkout 进行复现： ``` 7/7 gates exit 0 library build exit 0 · 210 entrypoints inherited spec suite 3765 SUCCESS browser gate 13/13 passed runtime deps tslib + four first-party angulux-* packages. Zero PrimeTek. ``` ### 2. 优先支持最新版 Angular，并作为公开承诺 这个承诺是：**在每次 Angular 大版本 RC 发布后的 14 天内实现绿色构建**，并由 夜间任务验证，该任务基于 `@angular/core@next` 进行构建并公开报告结果。angulux 的 大版本锁定对应 Angular 的大版本，因此 `angulux@22.x` 仅针对 Angular 22，绝无其他。 ### 3. 64 个受保障的模块，而非 117 个未经验证的模块 每个发布的模块都位于测试关卡覆盖的闭包内。另外 53 个模块位于 [`packages/angulux/attic/`](packages/angulux/attic/) 中——原封不动的上游源码，不进行构建， 不进行发布，作为路线图公开保留。提升其中一个模块是一项定义明确的贡献；请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## angulux 不是什么 - **不是直接替代品。** 选择器已更改。计划提供迁移的 codemod，但目前尚未发布。 - **不与 PrimeNG 达成功能对等。** 仅有 117 个模块中的 64 个。缺失的模块包括但不限于：Editor、 Tree、TreeSelect、OrganizationChart、PickList、OrderList、Listbox、Terminal、Dock。 （TreeTable **已**发布；Tree 没有。） - **不隶属于 PrimeTek 或 Google。** 请参阅 [NOTICE](NOTICE)。 - **不是受支持的产品。** MIT 协议，尽力而为，没有 SLA，没有响应时间承诺。 - **不是出于愤怒而创建的 fork。** PrimeTek 为社区贡献了十年的 MIT 协议工作，并 确认过去发布的 MIT 版本将保持 MIT 协议。这个项目正是因为那份授权而存在， 而不是无视它。请在 issue 和 pull request 中保持这种态度。 ## 环境要求 | | | |---|---| | Angular | `^22.0.0` | | TypeScript | `6.0.x` (Angular 22 的编译器要求 `>=6.0 <6.1`) | | Node | `>=22` | | 包管理器 | 开发环境使用 pnpm 9.6.0（通过 corepack）；安装使用时支持任何管理器 | `chart.js` 是一个可选的 peer dependency，仅 chart 模块需要。这里没有 `@angular/cdk` peer dependency ——它是被刻意移除的；在受保障闭包中的任何内容都不需要它。 ## 包 | 包 | 版本 | 用途 | |---|---|---| | [`angulux`](packages/angulux) | `22.x` | 组件库——大版本锁定对应 Angular 的大版本 | | [`angulux-styled`](packages/angulux-styled) | `1.x` | 样式引擎，fork 自 `@primeuix/styled` | | [`angulux-utils`](packages/angulux-utils) | `1.x` | DOM/对象实用工具，fork 自 `@primeuix/utils` | | [`angulux-styles`](packages/angulux-styles) | `1.x` | 基础样式定义 | | [`angulux-motion`](packages/angulux-motion) | `1.x` | 动画原语 | 这四个 fork 出来的包在 **`1.x` 上独立进行版本控制**——它们不依赖于 Angular， 因此将它们锁定在 Angular 的大版本上无异于在兼容性上撒谎。 ## 开发 ``` corepack pnpm install npm run check # the seven gates # 四个 fork 包在库之前构建 — 依赖顺序很重要 for p in utils styled motion styles; do (cd packages/angulux-$p && corepack pnpm run build) done corepack pnpm --filter angulux run build # → 210 entrypoints corepack pnpm --filter angulux run test:unit # → 3765 specs corepack pnpm --filter @angulux/verify run build npx playwright test --config e2e/playwright.config.ts # browser gate → 13/13 ``` `pnpm` 通过 corepack 运行，并且不在 `PATH` 中；请使用 `corepack pnpm`。如果 Chrome 不在默认位置，Karma 需要设置 `CHROME_BIN`。 ## 来源证明 [`PROVENANCE.md`](PROVENANCE.md) 记录了确切的上游提交、已归档的 MIT 工件及其校验和，以及你自行验证它们的命令。你不需要 盲目相信这里关于 MIT 的声明——我们为你提供了检查它的方法。这就是整个项目 的意义所在。 ### 认为来源证明在某处有误？ 那么这是你在这里能报告的最有价值的事情，它将被作为 P0 处理： [提出来源证明疑虑](https://github.com/anguless-com/angulux/issues/new/choose)。 一个要求你不要盲目信任它的项目，必须说到做到。这项声明会被审查，而不是 被辩护；如果声明被证实有误，受影响的代码将被移除，而不是被强词夺理地保留；如果是某道关卡 本应该发现这个问题，那么就会编写一道新的关卡；并且无论结果如何， 结果都会被公开，包括当报告被证明是错误的时候。如果你是提出法律主张的权利持有人，请使用 [私密渠道](https://github.com/anguless-com/angulux/security/advisories/new) 代替。 ## 许可证 MIT ——请参阅 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。

标签：Angular, Grype, MIT开源协议, UI组件库, 特征检测, 社区分支, 自动化攻击