@bbki.ng/ui 0.1.1

package/src/layout/grid/Grid.stories.tsx

@@ -0,0 +1,106 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Grid } from './Grid';
+
+const meta: Meta<typeof Grid> = {
+  title: 'Layout/Grid',
+  component: Grid,
+  tags: ['autodocs'],
+  argTypes: {
+    cols: {
+      control: 'select',
+      options: [1, 2, 3, 4, 6, 12],
+    },
+    gap: {
+      control: 'select',
+      options: ['none', 'sm', 'md', 'lg', 'xl'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const Box = ({ children }: { children: React.ReactNode }) => (
+  <div className="h-24 bg-[var(--semantic-color-muted)] rounded flex items-center justify-center text-[var(--semantic-color-foreground)]">
+    {children}
+  </div>
+);
+
+export const Default: Story = {
+  args: {
+    children: (
+      <>
+        <Box>1</Box>
+        <Box>2</Box>
+        <Box>3</Box>
+        <Box>4</Box>
+        <Box>5</Box>
+        <Box>6</Box>
+      </>
+    ),
+    cols: 3,
+    gap: 'md',
+  },
+};
+
+export const ColumnVariants: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {[2, 3, 4, 6].map(colCount => (
+        <div key={colCount}>
+          <p className="text-sm text-[var(--semantic-color-muted-foreground)] mb-2">
+            {colCount} columns
+          </p>
+          <Grid cols={colCount as 2 | 3 | 4 | 6} gap="md">
+            {Array.from({ length: colCount }).map((_, i) => (
+              <Box key={i}>{i + 1}</Box>
+            ))}
+          </Grid>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const GapVariations: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {(['none', 'sm', 'md', 'lg', 'xl'] as const).map(gapSize => (
+        <div key={gapSize}>
+          <p className="text-sm text-[var(--semantic-color-muted-foreground)] mb-2">
+            gap: {gapSize}
+          </p>
+          <Grid cols={3} gap={gapSize}>
+            <Box>1</Box>
+            <Box>2</Box>
+            <Box>3</Box>
+          </Grid>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const ThreeColumnLayout: Story = {
+  render: () => (
+    <div className="h-96 border border-[var(--semantic-color-border)] rounded">
+      <Grid
+        gap="md"
+        leftAside={
+          <div className="h-full bg-[var(--semantic-color-muted)] rounded p-4 text-[var(--semantic-color-foreground)]">
+            Left Sidebar
+          </div>
+        }
+        rightAside={
+          <div className="h-full bg-[var(--semantic-color-muted)] rounded p-4 text-[var(--semantic-color-foreground)]">
+            Right Sidebar
+          </div>
+        }
+      >
+        <div className="h-full bg-[var(--semantic-color-primary)]/10 rounded p-4 text-[var(--semantic-color-foreground)]">
+          Main Content Area
+        </div>
+      </Grid>
+    </div>
+  ),
+};

package/src/layout/grid/Grid.tsx

@@ -0,0 +1,86 @@
+import React from 'react';
+import { twMerge } from 'tailwind-merge';
+
+export interface GridProps {
+  children: React.ReactNode;
+  className?: string;
+  /** 列数 */
+  cols?: 1 | 2 | 3 | 4 | 6 | 12;
+  /** 间距 */
+  gap?: 'none' | 'sm' | 'md' | 'lg' | 'xl';
+  /** 响应式：移动端列数 */
+  mobileCols?: 1 | 2;
+  /** 左侧固定内容（三栏布局） */
+  leftAside?: React.ReactNode;
+  /** 右侧固定内容（三栏布局） */
+  rightAside?: React.ReactNode;
+}
+
+const gapMap = {
+  none: 'gap-0',
+  sm: 'gap-2',
+  md: 'gap-4',
+  lg: 'gap-6',
+  xl: 'gap-8',
+};
+
+const colsMap: Record<number, string> = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-2',
+  3: 'grid-cols-3',
+  4: 'grid-cols-4',
+  6: 'grid-cols-6',
+  12: 'grid-cols-12',
+};
+
+/**
+ * Grid 布局组件
+ *
+ * 支持标准网格和三栏布局（参考 MainLayout）。
+ */
+export const Grid: React.FC<GridProps> = ({
+  children,
+  className,
+  cols = 3,
+  gap = 'md',
+  mobileCols = 1,
+  leftAside,
+  rightAside,
+}) => {
+  // 三栏布局模式
+  if (leftAside || rightAside) {
+    return (
+      <div
+        className={twMerge(
+          'grid w-full h-full',
+          'grid-cols-1 md:grid-cols-3',
+          gapMap[gap],
+          className
+        )}
+      >
+        {leftAside && <div className="hidden md:block h-full overflow-auto">{leftAside}</div>}
+        <div className="h-full overflow-auto px-4">{children}</div>
+        {rightAside && <div className="hidden md:block h-full overflow-auto">{rightAside}</div>}
+      </div>
+    );
+  }
+
+  // 标准网格模式
+  const responsiveCols = mobileCols === 2 ? 'grid-cols-2' : 'grid-cols-1';
+
+  return (
+    <div
+      className={twMerge(
+        'grid w-full',
+        responsiveCols,
+        `md:${colsMap[cols]}`,
+        gapMap[gap],
+        className
+      )}
+    >
+      {children}
+    </div>
+  );
+};
+
+Grid.displayName = 'Grid';

package/src/layout/grid/index.ts

@@ -0,0 +1,2 @@
+export { Grid } from './Grid';
+export type { GridProps } from './Grid';

package/src/layout/index.ts

@@ -0,0 +1,4 @@
+export { Container } from './container';
+export type { ContainerProps } from './container';
+export { Grid } from './grid';
+export type { GridProps } from './grid';

package/src/molecules/article/Article.stories.tsx

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Article } from './Article';
+
+const meta: Meta<typeof Article> = {
+  title: 'Molecules/Article',
+  component: Article,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    title: '文章标题',
+    children: <p className="text-content-primary">这是文章内容。可以包含任意 React 节点。</p>,
+  },
+};
+
+export const WithDate: Story = {
+  args: {
+    title: '带日期的文章',
+    date: '2024-01-15',
+    children: <p className="text-content-primary">这篇文章带有发布日期。</p>,
+  },
+};
+
+export const WithDescription: Story = {
+  args: {
+    title: '带描述的文章',
+    description: '这是文章的描述/摘要部分',
+    children: <p className="text-content-primary">这是文章的详细内容。</p>,
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    title: '加载中',
+    loading: true,
+    children: <p className="text-content-secondary">内容正在加载中...</p>,
+  },
+};

package/src/molecules/article/Article.tsx

@@ -0,0 +1,25 @@
+import { twMerge } from 'tailwind-merge';
+import { BlinkDot } from '../../atoms/blink-dot';
+import { ArticleProps } from './Article.types';
+
+export const Article = (props: ArticleProps) => {
+  const { title, content, children, date, className, description, loading } = props;
+
+  return (
+    <div className={twMerge('relative', className)}>
+      <div className="mb-32 leading-none">
+        <span className="text-2xl mb-2 inline-block text-content-primary">{title}</span>
+        {loading && title && <BlinkDot status="blink" className="ml-2" />}
+        {date && (
+          <div className="px-2 pb-0 text-content-secondary">
+            <small>{date}</small>
+          </div>
+        )}
+      </div>
+      {description && <div className="mb-8 text-content-secondary">{description}</div>}
+      <div className="text-content-primary relative">{children || content}</div>
+    </div>
+  );
+};
+
+Article.displayName = 'Article';

package/src/molecules/article/Article.types.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+
+export interface ArticleProps {
+  title: ReactNode;
+  children?: ReactNode;
+  content?: ReactNode;
+  date?: string;
+  className?: string;
+  description?: ReactNode;
+  loading?: boolean;
+}

package/src/molecules/article/index.ts

@@ -0,0 +1,2 @@
+export { Article } from './Article';
+export type { ArticleProps } from './Article.types';

package/src/molecules/breadcrumb/Breadcrumb.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { MemoryRouter } from 'react-router-dom';
+import { Breadcrumb } from './Breadcrumb';
+
+const meta: Meta<typeof Breadcrumb> = {
+  title: 'Molecules/Breadcrumb',
+  component: Breadcrumb,
+  tags: ['autodocs'],
+  decorators: [
+    Story => (
+      <MemoryRouter>
+        <Story />
+      </MemoryRouter>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Breadcrumb>;
+
+const defaultPaths = [{ name: '~', path: '/' }, { name: 'ext', path: '/ext' }, { name: 'txt' }];
+
+const pathsWithCn = [
+  { name: '~', path: '/' },
+  { name: 'ext', path: '/ext' },
+  { name: 'txt', path: '/txt' },
+  { name: '与或非禁区' },
+];
+
+const pathsWithMultiCnWords = [
+  { name: '~', path: '/' },
+  { name: 'ext', path: '/ext' },
+  { name: '图片', path: '/png' },
+  { name: '县城' },
+];
+
+export const Default: Story = {
+  args: {
+    paths: defaultPaths,
+  },
+};
+
+export const WithChineseWords: Story = {
+  args: {
+    paths: pathsWithCn,
+  },
+};
+
+export const WithMultiChineseWords: Story = {
+  args: {
+    paths: pathsWithMultiCnWords,
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    paths: defaultPaths,
+    loading: true,
+  },
+};

package/src/molecules/breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import classNames from 'classnames';
+import { Link } from '../../atoms/link';
+import { BreadcrumbProps } from './Breadcrumb.types';
+
+/**
+ * Breadcrumb component for displaying navigation hierarchy
+ *
+ * Uses semantic color tokens and supports loading states.
+ * Automatically adjusts vertical offset for non-English characters.
+ *
+ * @example
+ * <Breadcrumb paths={[{ name: '~', path: '/' }, { name: 'ext', path: '/ext' }, { name: 'txt' }]} />
+ */
+export const Breadcrumb: React.FC<BreadcrumbProps> = ({ paths, loading }) => {
+  const PathElements = paths.map(({ path, name }, index) => {
+    // Separator slash between segments
+    const slash = index === 0 ? null : <span className="text-content-disabled">/</span>;
+
+    // Check if name contains non-English characters
+    const isNonEnName = !/^[a-zA-Z~]+$/.test(name);
+    const offsetCls = classNames({ 'relative top-[2px]': isNonEnName });
+
+    // Determine if this is the last segment
+    const isLast = index === paths.length - 1;
+
+    // Set status for loading indicator on the last segment
+    const status = loading && isLast ? 'blink' : 'hidden';
+
+    return (
+      <span key={path || name}>
+        {slash}
+        <Link to={path ?? ''} className={offsetCls} readonly={!path} status={status}>
+          {name}
+        </Link>
+      </span>
+    );
+  });
+
+  return <div className="breadcrumb">{PathElements}</div>;
+};
+
+Breadcrumb.displayName = 'Breadcrumb';

package/src/molecules/breadcrumb/Breadcrumb.types.ts

@@ -0,0 +1,19 @@
+/**
+ * Path object representing a single breadcrumb segment
+ */
+export type PathObj = {
+  /** Optional path for navigation. If not provided, the segment is displayed as text */
+  path?: string;
+  /** Display name for the breadcrumb segment */
+  name: string;
+};
+
+/**
+ * Props for the Breadcrumb component
+ */
+export type BreadcrumbProps = {
+  /** Array of path objects to display as breadcrumbs */
+  paths: PathObj[];
+  /** Whether the last breadcrumb segment is in loading state */
+  loading?: boolean;
+};

package/src/molecules/breadcrumb/index.ts

@@ -0,0 +1,2 @@
+export { Breadcrumb } from './Breadcrumb';
+export type { PathObj, BreadcrumbProps } from './Breadcrumb.types';

package/src/molecules/list/List.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { MemoryRouter } from 'react-router-dom';
+import { List, TitledList, LinkList } from './List';
+
+const meta: Meta<typeof List> = {
+  title: 'Molecules/List',
+  component: List,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+  },
+  decorators: [
+    Story => (
+      <MemoryRouter>
+        <Story />
+      </MemoryRouter>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const sampleItems = [
+  { id: 1, name: 'Item 1' },
+  { id: 2, name: 'Item 2' },
+  { id: 3, name: 'Item 3' },
+];
+
+export const Default: Story = {
+  args: {
+    items: sampleItems,
+    itemRenderer: (item: (typeof sampleItems)[0]) => (
+      <span className="text-content-primary">{item.name}</span>
+    ),
+  },
+};
+
+export const Horizontal: Story = {
+  args: {
+    items: sampleItems,
+    horizontal: true,
+    itemRenderer: (item: (typeof sampleItems)[0]) => (
+      <span className="text-content-primary px-2 py-1">{item.name}</span>
+    ),
+  },
+};
+
+export const WithFooter: Story = {
+  args: {
+    items: sampleItems,
+    footer: <span className="text-content-secondary">Footer content</span>,
+    itemRenderer: (item: (typeof sampleItems)[0]) => (
+      <span className="text-content-primary">{item.name}</span>
+    ),
+  },
+};
+
+export const Titled: StoryObj<typeof TitledList> = {
+  render: () => (
+    <TitledList
+      title="列表标题"
+      description="这是一个带标题的列表"
+      items={sampleItems}
+      itemRenderer={(item: (typeof sampleItems)[0]) => (
+        <span className="text-content-primary">{item.name}</span>
+      )}
+    />
+  ),
+};
+
+export const Links: StoryObj<typeof LinkList> = {
+  render: () => (
+    <LinkList
+      title="链接列表"
+      description="常用链接"
+      links={[
+        { to: '/', children: '首页' },
+        { to: '/about', children: '关于' },
+        { to: 'https://github.com', children: 'GitHub', external: true },
+      ]}
+    />
+  ),
+};

package/src/molecules/list/List.tsx

@@ -0,0 +1,79 @@
+import { twMerge } from 'tailwind-merge';
+import { Link, LinkProps } from '../../atoms/link';
+import { Article } from '../article';
+import { ListProps, TitledListProps, LinkListProps } from './List.types';
+
+export const List = (props: ListProps) => {
+  const { items, itemRenderer, className, horizontal, compact, footer, spaceBetween } = props;
+
+  const spaceCls = compact ? '' : horizontal ? 'mr-6' : 'mb-8';
+
+  return (
+    <ul
+      className={twMerge(
+        'list-none',
+        horizontal && 'flex items-center',
+        !horizontal && footer && spaceBetween && 'flex flex-col justify-between',
+        className
+      )}
+    >
+      {items.map((item, index) => {
+        return (
+          <li
+            key={item.id || index}
+            className={twMerge('shrink-0', spaceCls, horizontal && 'my-0')}
+          >
+            {itemRenderer(item, index)}
+          </li>
+        );
+      })}
+      {footer && (
+        <li key="footer" className={twMerge('shrink-0', horizontal && 'my-0')}>
+          {footer}
+        </li>
+      )}
+    </ul>
+  );
+};
+
+List.displayName = 'List';
+
+export const TitledList = (props: TitledListProps) => {
+  const { title, description, ...rest } = props;
+
+  if (!title) {
+    return <List {...rest} />;
+  }
+
+  return (
+    <Article title={title} description={description} className="w-fit">
+      <List {...rest} />
+    </Article>
+  );
+};
+
+TitledList.displayName = 'TitledList';
+
+export const LinkList = (props: LinkListProps) => {
+  const { title, description, links, ...rest } = props;
+
+  const renderLink = ({ children, to, external, ...linkRest }: LinkProps) => {
+    return (
+      <Link to={to || ''} external={external} {...linkRest}>
+        {children}
+      </Link>
+    );
+  };
+
+  return (
+    <TitledList
+      title={title}
+      description={description}
+      items={links}
+      itemRenderer={renderLink}
+      {...rest}
+    />
+  );
+};
+
+LinkList.displayName = 'LinkList';

package/src/molecules/list/List.types.ts

@@ -0,0 +1,23 @@
+import { ReactElement, ReactNode } from 'react';
+import { LinkProps } from '../../atoms/link';
+
+export interface ListProps {
+  items: any[];
+  itemRenderer: (itemProps: any, index: number) => ReactElement;
+  className?: string;
+  compact?: boolean;
+  horizontal?: boolean;
+  footer?: ReactNode;
+  spaceBetween?: boolean;
+}
+
+export interface TitledListProps extends ListProps {
+  title?: ReactNode;
+  description?: ReactNode;
+}
+
+export interface LinkListProps extends Omit<ListProps, 'itemRenderer' | 'items'> {
+  title?: string;
+  description?: ReactNode;
+  links: LinkProps[];
+}

package/src/molecules/list/index.ts

@@ -0,0 +1,2 @@
+export { List, TitledList, LinkList } from './List';
+export type { ListProps, TitledListProps, LinkListProps } from './List.types';

package/src/molecules/nav/Nav.stories.tsx

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { MemoryRouter } from 'react-router-dom';
+import { Nav } from './Nav';
+
+const meta: Meta<typeof Nav> = {
+  title: 'Molecules/Nav',
+  component: Nav,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+  },
+  decorators: [
+    Story => (
+      <MemoryRouter>
+        <Story />
+      </MemoryRouter>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    paths: [{ name: '~', path: '/' }, { name: 'ext', path: '/ext' }, { name: 'txt' }],
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    paths: [
+      { name: '~', path: '/' },
+      { name: 'loading', path: '/loading' },
+    ],
+    loading: true,
+  },
+};
+
+export const Mini: Story = {
+  args: {
+    paths: [{ name: 'ext', path: '/ext' }, { name: 'txt' }],
+    mini: true,
+  },
+};

package/src/molecules/nav/Nav.tsx

@@ -0,0 +1,29 @@
+import { twMerge } from 'tailwind-merge';
+import { useNavigate } from 'react-router-dom';
+import { Breadcrumb } from '../breadcrumb';
+import { Logo } from '../../atoms/logo';
+import { NavProps } from './Nav.types';
+
+export const Nav = (props: NavProps) => {
+  const { paths, loading, mini, className, customLogo } = props;
+  const nav = useNavigate();
+
+  if (mini) {
+    return (
+      <div className={twMerge('p-2 w-full flex items-center', className)}>
+        <Breadcrumb paths={paths} />
+      </div>
+    );
+  }
+
+  return (
+    <div className={twMerge('p-2 w-full flex items-center', className)}>
+      {customLogo || (
+        <Logo className="mr-2 cursor-pointer hover:opacity-80" onClick={() => nav('/')} />
+      )}
+      <Breadcrumb paths={paths} loading={loading} />
+    </div>
+  );
+};
+
+Nav.displayName = 'Nav';