@ crometics/ lp- 设计系统

React 18/19 组件库用于登陆页面. 船舶未捆绑的无害环境管理(每个单元一个) 和独立的样式表; 消费者仅通过 --lp-* CSS 变量和不需要 尾风自设.

安装

该套件公开发布至npm:

pnpm add @crometrics/lp-design-system

通过0.5.0的放出也去了GitHub套件;后期的放出只有npm. 另一个 @crometrics 软件包仍然被发布到 GitHub 软件包。 狦 .npmrc (项目或 ~/.npmrc) 绘制那里的范围—— @crometrics:registry=https://npm.pkg.github.com/ ——这种绘图适用于每一个 @crometrics 软件包,因此上面的命令会针对 GitHub 软件包解析,而永远不会看到 npm发布. 如果您不需要其他地图, 要么删除映射 @crometrics 软件包,或指针 以 pnpm 为单位的 npm 软件包 npmjs: 登记册前缀(pnpm 11.1+):

pnpm add "@crometrics/lp-design-system@npmjs:^0.5.0"

用于保存 "@crometrics/lp-design-system": "npmjs:^0.5.0" 改为 package.json更新 从 npm 而从其他 @crometrics gitHub 软件包中仍然有解析。 无 而Yarn没有每个包装的注册系统.

react 财务报告和审定财务报表 react-dom ^18.0.0 || ^19.0.0 属于对等依赖,必须安装于 消费者。 每一个故事测试都运行在 Resact 18.3.1(HubSpot CMS React pins)和 反应19.

使用量

在应用根导入样式表, 然后在任何地方使用组件 :

// app entry (e.g. src/main.tsx, or app/layout.tsx in Next.js)
import '@crometrics/lp-design-system/styles.css';

从自己的入口——kebab- case 组件名称导入每个组件:

import { Button } from '@crometrics/lp-design-system/button';
import { PromoBanner } from '@crometrics/lp-design-system/promo-banner';

每个组件入口只装入每个工具中的组件模块: 生产捆绑、dev服务器和测试跑道 从软件包导入 根数( e)import { Button } from '@crometrics/lp-design-system'(b) 工程和 生产过程中的树摇摆正在建立,但dev服务器和测试跑取器每加载 组件通过它.

import { Button } from '@crometrics/lp-design-system/button';

export default function Page() {
  return (
    <>
      <Button>Primary</Button>
      <Button variant="secondary" size="lg">
        Secondary
      </Button>
      <Button variant="tertiary" icon={<CameraIcon />}>
        With icon
      </Button>
      <Button
        variant="transparent"
        icon={<img alt="" src={logo} />}
        iconPosition="trailing"
      >
        On a hero image
      </Button>
      <Button aria-label="Add photo" icon={<CameraIcon />} round />
    </>
  );
}

服务器渲染和水分

每个组件的服务器发送器( 验证为 renderToString (原始内容存档于2018-11-19). React 18 and 19. 只有两个人需要客户水合——在HubSpot CMS React中,使其成为岛屿:

其他一切——包括: Header, (中文(简体) ), TrustSignalsMetrics, (中文(简体) ), ThirtyNinety, (中文(简体) ), PromoBanner, (中文(简体) ), Accordion (Base UI将自己的原始水合物)和 FooterMega —— 说 无组件 JavaScript。 与 formSlot, (中文(简体) ), DonationHero 无需水合 它的自身 超越了任何时间档的供应商 嵌入带来的.

部件也是RSC安全: Tout 财务报告和审定财务报表 DonationForm 标记 'use client',所以在 Next.js App路由器和 没有将组件 JavaScript 传送到浏览器 。 两者都可以直接从服务器中渲染 组件 - 不需要折叠文件。 无 RSC 框架( Vite SPAs, Astro, plain) 反应)忽略指令.

从服务器组件传递的道具必须是可序列的: 事件处理器, 如 Input是因为 onChange 或者说 EmailSignupForm是因为 onSubmit 只能从一个 客户端组件.

他们

--lp-* 自定义属性是整个公共造型 API。 默认声明于 :root 内 styles.css; 覆盖您 CSS 中的任意一个, 并装入 库样式表 :

:root {
  --lp-color-primary: #16a34a;
}

默认镜像 Figma “ 页面设计系统” 库 .

断点

布局遵循设计的三个页面框架: 移动 < 1024px, (中文(简体) ), 桌面 1024–1727px (英语), (中文(简体) ), 宽度为 1728px。反应符号默认值在这些宽度下切换,以及 主题覆盖同一媒体查询中响应的符号 :

:root {
  --lp-text-h1-cms-size: 2.5rem;
} /* mobile + desktop */
@media (min-width: 1728px) {
  :root {
    --lp-text-h1-cms-size: 4rem;
  } /* wide */
}

在0.5.0之前,宽层开始于1280px.

样式表不会重新显示您的页面 。 它确实在自己的组件内重新设置: 组件根带 a data-lp 属性,并重置零特性(Tailwind's 飞行前,范围扩大到 [data-lp] 子树)清除浏览器默认存在, 如标题 和段落边距、链接颜色和下划线以及本地按钮边框。 重置坐着 输入 lp-base 级联层和工具类 lp。任何没有层次的 CSS 在您的 页面的分数都高于两者,所以全球规则就像 h2 { margin-bottom: 1rem } 您的主题仍然 到达我们的标题。 这些规则的范围,不包括 [data-lp] 如果他们干涉。 类 除这些变量外,其他名称是执行细节,在任何发布中都可能有所改变.

构成部分

每个区块的全 CMS- faccing 形状(道具,切换器,中继器,变体,插槽)在 contracts/<Name>.json。在0.5.0中添加,所有可选的默认值都保留 上一个渲染 :

0.6.0中的添加, 也带有保留上一个渲染的默认的可选性 :

添加到 0.7. 0 中, 并带有默认保存上一个渲染的选项 :

CtaLink (单位:千美元){ href, label, newTab?, id?, dataAttributes? })是用于 Header, (中文(简体) ), TrustSignalsMetrics, (中文(简体) ), ThirtyNinety 财务报告和审定财务报表 PromoBanner。 。 。 . id 财务报告和审定财务报表 dataAttributes (键必须从 data-(其他被丢弃) CTA 元素,所以您自己的脚本可以瞄准它,例如用于分析或打开一个 第三方捐款表,如筹款:

<Header
  logo={logo}
  ctas={[
    {
      link: {
        label: 'Get started',
        href: '#signup',
        dataAttributes: { 'data-track': 'header-primary' },
      },
      hideOnMobile: true,
    },
    { link: { label: 'Contact us', href: '#contact', id: 'header-contact' } },
  ]}
/>;

页脚Mega 注册表

FooterMega 使任何你通过的形式 signupSlot: CMS 格式模块,一个 电子邮件提供者嵌入, 或者您自己的标记 。 它不可能知道这个标记,所以 signupFormSelectors 告诉它哪一个元素 得到注册设计的每个部分. 每个密钥都是可选的,并使用任何 CSS 选择器列表,在页脚的槽内匹配 只有这个 没有密钥匹配的元素继承了槽的字体,大小和颜色.

例如,对于一个使用标记的表单模块 .hs-* 如HubSpot所言:

<FooterMega
  {...footerProps}
  signupFormSelectors={{
    error: '.hs-error-msgs',
    field: '.hs-input:not([type=checkbox], [type=radio])',
    fieldInvalid: '.hs-input.error',
    fieldRow: 'fieldset',
    form: '.hs-form',
    hiddenLabel:
      '.hs-form-field:not(.hs-fieldtype-checkbox, .hs-fieldtype-booleancheckbox, .hs-fieldtype-radio) > label',
    hint: '.hs-richtext',
    inlineField: 'fieldset:last-of-type',
    inlineSubmit: '.hs-submit',
    reset: '.input, .actions',
    submit: '.hs-button',
  }}
  signupSlot={<YourFormModule />}
/>

脚步使这些规则在 <style> 插槽内 lp 层,所以你 自己的 CSS 仍然覆盖它们; 嵌入自己样式表的少数布局声明 通常战斗(宽度、浮度、包边、隐藏标签)是 !important颜色 跟着 style 编辑 --lp-* 变量。 包含 {, (中文(简体) ), }, (中文(简体) ), ;, (中文(简体) ), < 或一个 评论掷出. 对于一个需要这些密钥中任何一个都未给出的外观的元素,请将其样式化入 您的 CSS 属于 [data-lp-part="signup-slot"] 与 --lp-* 变量.

类型合同

contracts/<Name>.json (说明 contracts/component.schema.json) 扩大每个 输入为 JSON 时的文字 . @crometrics/lp-design-system/contracts 出口情况相同 数据及其字面类型,如 <Name>Contract,加上与之相关的类型:

import {
  type ContractProp,
  type ContractValues,
  HeaderContract,
} from '@crometrics/lp-design-system/contracts';

// Props, variants and repeater items share one union, discriminated on `type`.
const field = (prop: ContractProp) => {
  switch (prop.type) {
    case 'enum':
      return prop.options; // readonly [string, ...string[]]
    case 'link':
      return prop.fields; // subset of 'label' | 'href' | 'newTab' | 'id' | 'dataAttributes'
    // …
  }
};

// The props a contract describes: { logo: { src; alt }; logoSize?: 'md' | 'lg'; … }
type HeaderValues = ContractValues<typeof HeaderContract>;

ContractValues 地图 text 改为 string, (中文(简体) ), boolean, (中文(简体) ), number, (中文(简体) ), enum 对它的选择, image 改为 { src, alt } 财务报告和审定财务报表 link 改为 Pick<CtaLink, …fields>A级 richtext 道具 顺其自然 render 模式 : html 道具被注入到一个 dangerouslySetInnerHTML这样 他们拿走了CMS的HTML string· ; node 道具是作为反应儿童提供的,所以 带一个 ReactNode。将 HTML 变成这些元素(原始 HTML 字符串将显示) 逃脱). 中继器变成数组: 需要的非空的 Tuple [T, ...T[]] 何时 min ≥ 1,其他选择。 点数密钥( N)form.submitLabel)成为被嵌入物. required 控制密钥是否是可选的,变量总是可选的. hidden 道具和插槽被忽略(插槽是 ReactNode 道具,喜欢 formSlot 或者说 signupSlot使你变成你自己 countFrom 变体,例如 BannerGrid是因为 quantity:它们只大小其中继器,组件读取 数组长度 。 也导出 : Contract, (中文(简体) ), ContractVariant, (中文(简体) ), ContractRepeater, (中文(简体) ), ContractSlot, (中文(简体) ), ContractPropValue<P>, (中文(简体) ), ContractRichtextRender,每个接口 道具类型( e)TextProp, (中文(简体) ), RichtextProp<Render>, (中文(简体) ), EnumProp, (中文(简体) ), LinkProp(中文(简体) ).

mapContract

@crometrics/lp-design-system/contracts/map 帮你签合同 你来一个 每叶类型输入读取器,返回 ContractValues<C>,没有断言 你那边:

import { ToutContract } from '@crometrics/lp-design-system/contracts';
import {
  type ContractReaders,
  mapContract,
} from '@crometrics/lp-design-system/contracts/map';

const text = (value: unknown) =>
  typeof value === 'string' ? value : undefined;

const read: ContractReaders = {
  boolean: (value) => (typeof value === 'boolean' ? value : undefined),
  enum: text, // mapContract drops values that aren't one of the options
  image: (value) => toImage(value),
  link: (value) => toCtaLink(value),
  number: (value) => (typeof value === 'number' ? value : undefined),
  richtext: {
    html: text, // must return a string
    node: (value) =>
      typeof value === 'string' ? htmlToReact(value) : undefined,
  },
  text: (value, prop) => text(value) ?? prop.default,
};

const props = mapContract(ToutContract, fieldValues, read); // ToutProps-compatible

每个读者都得到原始价值,道克的契约条目及其路径(sectionHeading, (中文(简体) ), cards[1].body, (中文(简体) ), variants.cards) (中文(简体) ). fieldValues 反映合同:道具和 中继器坐在被点的密钥上({ form: { submitLabel } }),中继器为 项目对象,变量在下方 variants同样的方式 countFrom 给他们起名 (单位:千美元){ cards: […], variants: { cards: '3' } }) (中文(简体) ). 隐藏和插槽道具被跳过. A 类 countFrom 中继器被调整到其变量值(或默认值). 一个读者 返回时 undefined 离开道具,所以组件默认适用。 对a required 道具,或一个 min ≥ 1 中继器,最后是空的, mapContract 掷出 相反,因为道具类型 承诺了一个价值。 倒车 prop.default 输入 读者要避免这一点.

少数合同并没有准确描述它们的组件道具,所以CMS适配器有 以映射这些字段. contracts/props.test-d.ts 每个和任何其他 合同与合同组成部分之间的差值未通过类型测试:

发展

从此软件包目录中运行 :

pnpm storybook   # dev at http://localhost:6006
pnpm test        # runs the stories headless via addon-vitest
pnpm build       # dist/*.js per component (tsdown) + dist/styles.css (@tailwindcss/cli)

故事就是测试:每个元件行为都是在 *.stories.tsx 播放函数而不是单独的 spec 文件.