演示目录只保留可重建的源码。运行密钥、数据卷、依赖和带口令的本地配置不进入仓库。 Co-authored-by: Cursor <cursoragent@cursor.com>
97 lines
5.1 KiB
Markdown
97 lines
5.1 KiB
Markdown
# Public API Authoring
|
|
|
|
Each `src/<primitive>/index.tsx` is an explicit public API boundary. Keep implementation details
|
|
module-local and publish the complete surface through separate `export { ... }` and
|
|
`export type { ... }` manifests at the bottom of the file. Do not mix scattered inline exports
|
|
with the manifest or use wildcard exports.
|
|
|
|
## Base UI imports
|
|
|
|
Import a Base UI part once per module and read its types from that binding's namespace, such as
|
|
`BaseRadio.Root.Props`. Use `import type` only when the module has no runtime use of the part. Do
|
|
not keep a value import and a type import of the same module side by side.
|
|
|
|
Add a public utility subpath only when an application consumer needs it. Inside the package,
|
|
use an existing utility entrypoint; otherwise import directly from `@base-ui/utils`.
|
|
|
|
## React imports
|
|
|
|
Use React namespace imports throughout this package, including stories and tests. Use
|
|
`import * as React from 'react'` when calling React runtime APIs, and
|
|
`import type * as React from 'react'` when referencing only React types. A runtime namespace
|
|
import also covers React types; do not add separate named type imports. JSX alone does not
|
|
require an explicit React import.
|
|
|
|
Use namespace imports for `react-dom`, `react-dom/client`, and `react-dom/server` as well.
|
|
Write grouping fragments as `<React.Fragment>` and remove unnecessary fragment wrappers.
|
|
|
|
## Component writing style
|
|
|
|
Define named components with function declarations or function expressions. Arrow functions
|
|
remain appropriate for event handlers, render props, and Storybook render callbacks. Name function
|
|
expressions when JavaScript cannot infer their name. Use `event` or `error` instead of `e`.
|
|
|
|
## Subpaths and names
|
|
|
|
Every public primitive needs a matching `package.json#exports` subpath. Import relatively between
|
|
package components; consumers import only through public subpaths.
|
|
|
|
Keep package-private helpers in `src/internal/`; top-level runtime utility modules in `src/` are
|
|
public utility subpaths. Components share code through the owning component's entrypoint or an
|
|
explicit internal module, not another component's implementation files.
|
|
|
|
Use the primitive name without a `Root` suffix for the canonical boundary and matching props type:
|
|
`Select` and `SelectProps`, `Drawer` and `DrawerProps`.
|
|
|
|
Every runtime component must have an accurate, importable props type with the matching name. Use a
|
|
direct alias for an unchanged Base UI part. Define Dify-authored composite props at the Dify UI
|
|
boundary instead of copying upstream shapes.
|
|
|
|
Use a discriminated union when one prop changes the valid shape of related props, such as
|
|
controlled versus uncontrolled state or single versus multiple selection.
|
|
|
|
## Generic contracts
|
|
|
|
Preserve generic relationships end to end, including picker `Value` and `Multiple`, form values,
|
|
radio and slider values, and overlay payloads or handles. Do not erase caller-owned types with
|
|
`any` or a hard-coded `string`. Use `unknown` only as the safe default for independently consumed
|
|
anatomy whose value JSX cannot infer from its parent.
|
|
|
|
Do not add a root-only generic when separately rendered anatomy can produce values outside the
|
|
root's inferred type. Preserve the upstream contract until the whole component family can enforce
|
|
one value type. `Tabs` intentionally follows Base UI's non-generic root because its current tab
|
|
value type is `any | null`; do not advertise a type relationship the complete anatomy cannot
|
|
enforce.
|
|
|
|
Preserve upstream anatomy when its parts own distinct semantics, interaction, or positioning.
|
|
Create a Dify-authored convenience component only when the package adds a shared contract; do not
|
|
hide primitive parts merely to shorten a consumer call site.
|
|
|
|
## Keep the public surface small
|
|
|
|
A type is not public merely because Base UI names it or an implementation once exported it. In
|
|
addition to matching component props, export a type only when it pairs with a public factory or a
|
|
real consumer must name it independently.
|
|
|
|
State, controlled-state helpers, context values, render helpers, styling helpers, and upstream
|
|
passthrough aliases are private by default. Public props already provide contextual typing for
|
|
inline render and event callbacks. Expose styling helpers only when consumers need to reuse
|
|
appearance independently.
|
|
|
|
Event details and reasons are the exception. A component that aliases or wraps a Base UI part
|
|
re-exports that part's `*EventDetails` and `*EventReason` types under its own name. A composite
|
|
that only uses a part internally does not. `State` and enum namespaces stay private.
|
|
|
|
Preserve upstream `className` and `style` callbacks. Resolve `className` with the owning Base UI
|
|
part's state before merging default classes with `cn()`, including through composite wrappers.
|
|
Forward `style` unchanged unless the wrapper needs to merge styles; then resolve its callback first.
|
|
Do not add state callbacks to native DOM props or unrelated custom APIs. See [Styling].
|
|
|
|
## Evidence
|
|
|
|
Use local public-subpath type tests to protect generic inference, required relationships, and
|
|
intentional errors. Read current official Base UI documentation and installed type declarations
|
|
before changing an upstream-derived contract.
|
|
|
|
[Styling]: ./styling.md
|