npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@composy/breadcrumb-core

v0.0.2

Published

LDesign breadcrumb framework-agnostic core library

Readme

@composy/breadcrumb-core

LDesign 面包屑导航框架无关核心:状态管理器、路由/路径工具、事件类型、样式契约、Engine 插件与 SSR 安全的 Web Component,供各框架适配层复用。

✨ 核心能力

  • 状态管理器:BreadcrumbManager 统一管理面包屑项、展开态与可见性裁剪
  • 历史快照:createSnapshot() / restoreSnapshot() 与 undo() / redo() 撤销重做
  • 折叠策略:支持 ellipsis / dropdown / none 三种折叠模式与前后保留数量预算
  • 路径工具:parsePath()、resolveItemHref()、serializeQuery() 等路由辅助函数
  • 样式契约:统一的类名前缀、CSS 变量生成器与默认主题变量表
  • Web Component:SSR 安全的 <ldesign-breadcrumb> 自定义元素
  • Engine 插件:createBreadcrumbEnginePlugin() 适配上层 Engine 生态

resolveItemHref() rejects javascript:, data:, and vbscript: URLs (including those with embedded ASCII control characters). BreadcrumbManager requires finite collapse and history limits; invalid updates leave its current config unchanged.

📦 安装

pnpm add @composy/breadcrumb-core

🚀 快速开始

import { BreadcrumbManager } from '@composy/breadcrumb-core'

const manager = new BreadcrumbManager({
  items: [
    { key: 'workspace', label: 'Workspace', path: '/workspace' },
    { key: 'projects', label: 'Projects', path: '/workspace/projects' },
  ],
  separator: 'chevron',
  density: 'compact',
  maxItems: 4,
  collapseMode: 'dropdown',
  enableHistory: true,
})

manager.addItem({
  key: 'atlas',
  label: 'Atlas Program',
  path: '/workspace/projects/atlas',
})

manager.undo()
manager.redo()

📖 Manager API

BreadcrumbManager 主要方法:

  • getConfig()、getState()、getItems()、getItem(key)、getItemIndex(key)
  • getVisibleItems()、count、isExpanded、version
  • setItems(items)、addItem(item, index?)、removeItem(key)、updateItem(key, updates)
  • batch(callback)、toggleExpand()、setExpanded(expanded)
  • updateConfig(config)
  • on(event, handler)、once(event, handler)、off(event, handler)
  • createSnapshot()、restoreSnapshot(snapshot)
  • undo()、redo()、canUndo、canRedo、clearHistory()
  • destroy()、isDestroyed

事件:

  • click
  • dropdownSelect
  • expandChange

🧱 数据结构

import type { BreadcrumbItem } from '@composy/breadcrumb-core'

const item: BreadcrumbItem = {
  key: 'projects',
  label: 'Projects',
  path: '/workspace/projects/:project',
  params: { project: 'atlas' },
  query: { tab: 'overview' },
  children: [
    { key: 'active', label: 'Active projects', path: '/workspace/projects?state=active' },
    {
      key: 'archived',
      label: 'Archived projects',
      path: '/workspace/projects?state=archived',
      divider: true,
    },
  ],
}

⚙️ 配置参考

type BreadcrumbSeparator = 'slash' | 'arrow' | 'dot' | 'chevron' | string
type BreadcrumbSize = 'small' | 'medium' | 'large'
type BreadcrumbDensity = 'default' | 'compact' | 'comfortable'
type BreadcrumbCollapseMode = 'ellipsis' | 'dropdown' | 'none'

常用配置字段:

| 字段 | 说明 | | -------------------------------------------------------------------- | -------------------------- | | items | 面包屑项列表 | | separator | 分隔符样式 | | size / density | 尺寸与密度 | | maxItems | 最大可见项数 | | itemsBeforeCollapse / itemsAfterCollapse | 折叠时首尾保留数 | | collapseMode | 折叠模式 | | showHome / homeItem | 是否展示首页项及自定义首页 | | lastItemClickable | 末项是否可点击 | | ariaLabel / expandLabel / collapsedDropdownLabel / moreLabel | 无障碍与文案 | | enableHistory / maxHistoryLength | 历史记录开关与上限 |

🔧 工具函数

import {
  calculateVisibleItems,
  getSeparatorChar,
  normalizeItems,
  parsePath,
  resolveItemHref,
  serializeQuery,
} from '@composy/breadcrumb-core'

const items = parsePath('/workspace/projects/atlas/releases', {
  includeRoot: true,
})

const href = resolveItemHref({
  path: '/workspace/projects/:project/releases',
  params: { project: 'atlas' },
  query: { month: 'march' },
})

const query = serializeQuery({
  page: 2,
  filters: ['active', 'critical'],
})

🎨 样式契约

核心导出共享的类名与 token 工具:

import {
  BREADCRUMB_CLASS_PREFIX,
  BREADCRUMB_CSS_VAR_PREFIX,
  BREADCRUMB_DEFAULT_THEME_VARIABLES,
  breadcrumbClassNames,
  createBreadcrumbCssText,
  createBreadcrumbCssVariables,
  getBreadcrumbCssVariableName,
  getBreadcrumbCssVariableReference,
} from '@composy/breadcrumb-core/styles'
  • 公共类名使用 ldesign-breadcrumb 前缀;组件变量使用 --ldesign-breadcrumb-* 前缀
  • 默认变量把颜色映射到 packages/color 生成的 --ld-* token,把尺寸、间距、圆角、字体、边框与模糊值映射到 packages/size 生成的 --ld-* token

示例:

:root {
  --ldesign-breadcrumb-text-color: var(--ld-text-secondary);
  --ldesign-breadcrumb-current-color: var(--ld-text-primary);
  --ldesign-breadcrumb-item-height: var(--ld-px-34);
  --ldesign-breadcrumb-radius: var(--ld-radius-pill);
}

🧩 Web Component

import { defineLDesignBreadcrumbElement } from '@composy/breadcrumb-core/web-components'

defineLDesignBreadcrumbElement()
<ldesign-breadcrumb
  items='[{"key":"home","label":"Home","path":"/"},{"key":"docs","label":"Docs","path":"/docs"}]'
></ldesign-breadcrumb>

实现对 HTMLElement 的访问做了守卫,在 SSR 环境导入模块也是安全的。

📤 导出入口一览

import type { BreadcrumbItem } from '@composy/breadcrumb-core/types'
import { BreadcrumbManager } from '@composy/breadcrumb-core'
import { createBreadcrumbEnginePlugin } from '@composy/breadcrumb-core/engine'
import { breadcrumbClassNames } from '@composy/breadcrumb-core/styles'
import { parsePath } from '@composy/breadcrumb-core/utils'
import { defineLDesignBreadcrumbElement } from '@composy/breadcrumb-core/web-components'

🔨 构建产物与验证

构建由本包 .ldesign/builder.config.ts 中的 @composy/builder / Rolldown 配置负责;TypeScript canonical 配置位于 .ldesign/tsconfig.json 和 .ldesign/tsconfig.cjs.json,包根 tsconfig*.json 保留兼容转发。

构建产物目录:

dist/
es/
esm/
lib/
pnpm run type-check   # 类型检查
pnpm run build        # 四产物构建(@composy/builder)
pnpm run test         # 单元测试

🔗 相关链接

📄 License

MIT License © LDesign Team