feat: add breadcrumb and breadcrumbItem components (#123)

* feat: add breadcrumb and breadcrumbItem components

* feat: add types, fix lint warn

* feat: add KSymbolKey fn, rewrite breadcrumb key

components/Breadcrumb/__test__/__snapshots__/breadcrumb.spec.ts.snap

@@ -0,0 +1,3 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Test: KBreadcrumb > props: cls 1`] = `"<div class=\\"k-breadcrumb k-breadcrumb--test\\"></div>"`;

components/Breadcrumb/__test__/breadcrumb.spec.ts

@@ -0,0 +1,30 @@
+import { afterEach, expect, test, describe, beforeEach } from 'vitest';
+import KBreadcrumb from '../src';
+
+let host: HTMLElement;
+
+const initHost = () => {
+	host = document.createElement('div');
+	host.setAttribute('id', 'host');
+	document.body.appendChild(host);
+};
+beforeEach(() => {
+	initHost();
+});
+afterEach(() => {
+	host.remove();
+});
+
+describe('Test: KBreadcrumb', () => {
+	test('props: cls', async () => {
+		const instance = new KBreadcrumb({
+			target: host,
+			props: {
+				cls: 'k-breadcrumb--test'
+			}
+		});
+		expect(instance).toBeTruthy();
+		expect((host as HTMLElement)!.innerHTML.includes('k-breadcrumb--test')).toBeTruthy();
+		expect(host.innerHTML).matchSnapshot();
+	});
+});

components/Breadcrumb/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "@ikun-ui/breadcrumb",
+	"version": "0.0.9-beta.2",
+	"type": "module",
+	"main": "dist/index.js",
+	"module": "dist/index.js",
+	"svelte": "dist/index.js",
+	"types": "src/index.ts",
+	"keywords": [
+		"svelte",
+		"svelte3",
+		"web component",
+		"component",
+		"react",
+		"vue",
+		"svelte-kit",
+		"dx"
+	],
+	"scripts": {
+		"build": "npm run build:js && npm run build:svelte",
+		"build:js": "tsc -p . --outDir dist/ --rootDir src/",
+		"build:svelte": "svelte-strip strip src/ dist",
+		"publish:npm": "pnpm publish --no-git-checks --access public"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@ikun-ui/icon": "workspace:*",
+		"@ikun-ui/utils": "workspace:*",
+		"baiwusanyu-utils": "^1.0.14"
+	},
+	"devDependencies": {
+		"@tsconfig/svelte": "^5.0.0",
+		"svelte-strip": "^2.0.0",
+		"tslib": "^2.6.1",
+		"typescript": "^5.1.6"
+	}
+}

components/Breadcrumb/src/index.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+	import { setContext } from 'svelte';
+	import { getPrefixCls, createCls, BreadcrumbKey } from '@ikun-ui/utils';
+
+	export let separator: string = '/';
+	export let separatorIcon: string = '';
+	export let cls: string = '';
+	export let attrs: Record<string, string> = {};
+
+	setContext(BreadcrumbKey, {
+		separator,
+		separatorIcon
+	});
+
+	// class names
+	const prefixCls = getPrefixCls('breadcrumb');
+	$: cnames = createCls(prefixCls, cls);
+</script>
+
+<div class={cnames} {...$$restProps} {...attrs}>
+	<slot />
+</div>

components/Breadcrumb/src/index.ts

@@ -0,0 +1,5 @@
+/// <reference types="./types" />
+import Breadcrumb from './index.svelte';
+export { Breadcrumb as KBreadcrumb };
+
+export default Breadcrumb;

components/Breadcrumb/src/types.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="svelte" />
+export type KBreadcrumbProps = {
+	separator: string;
+	separatorIcon: string;
+	cls: string;
+	attrs: Record<string, string>;
+};

components/Breadcrumb/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"extends": "@tsconfig/svelte/tsconfig.json",
+
+	"compilerOptions": {
+		"noImplicitAny": true,
+		"strict": true,
+		"declaration": true
+	},
+	"include": ["src/**/*.ts", "src/**/*.svelte"],
+	"exclude": ["node_modules/*", "**/*.spec.ts"]
+}

components/BreadcrumbItem/__test__/__snapshots__/breadcrumb-item.spec.ts.snap

@@ -0,0 +1,7 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Test: KBreadcrumbItem > props: cls 1`] = `"<span class=\\"k-breadcrumb-item k-breadcrumb-item--test\\"><span class=\\"k-breadcrumb-item-content k-breadcrumb-item-content__dark\\" href=\\"\\"></span> <span class=\\"k-breadcrumb-item-separator k-breadcrumb-item-separator__dark\\">/</span></span>"`;
+
+exports[`Test: KBreadcrumbItem > props: href is empty 1`] = `"<span class=\\"k-breadcrumb-item\\"><span class=\\"k-breadcrumb-item-content k-breadcrumb-item-content__dark\\" href=\\"\\"></span> <span class=\\"k-breadcrumb-item-separator k-breadcrumb-item-separator__dark\\">/</span></span>"`;
+
+exports[`Test: KBreadcrumbItem > props: href is not empty 1`] = `"<span class=\\"k-breadcrumb-item\\"><a class=\\"k-breadcrumb-item-content k-breadcrumb-item-content__dark k-breadcrumb-item-link\\" href=\\"https://github.com/ikun-svelte/ikun-ui\\"></a> <span class=\\"k-breadcrumb-item-separator k-breadcrumb-item-separator__dark\\">/</span></span>"`;

components/BreadcrumbItem/__test__/breadcrumb-item.spec.ts

@@ -0,0 +1,57 @@
+import { afterEach, expect, test, describe, beforeEach } from 'vitest';
+import KBreadcrumbItem from '../src';
+
+let host: HTMLElement;
+
+const initHost = () => {
+	host = document.createElement('div');
+	host.setAttribute('id', 'host');
+	document.body.appendChild(host);
+};
+beforeEach(() => {
+	initHost();
+});
+afterEach(() => {
+	host.remove();
+});
+
+describe('Test: KBreadcrumbItem', () => {
+	test('props: cls', async () => {
+		const instance = new KBreadcrumbItem({
+			target: host,
+			props: {
+				cls: 'k-breadcrumb-item--test'
+			}
+		});
+		expect(instance).toBeTruthy();
+		expect((host as HTMLElement)!.innerHTML.includes('k-breadcrumb-item--test')).toBeTruthy();
+		expect(host.innerHTML).matchSnapshot();
+	});
+
+	test('props: href is empty', async () => {
+		const instance = new KBreadcrumbItem({
+			target: host,
+			props: {
+				href: ''
+			}
+		});
+		expect(instance).toBeTruthy();
+		expect((host as HTMLElement)!.innerHTML.includes('k-breadcrumb-item-link')).toBeFalsy();
+		expect(host.innerHTML).matchSnapshot();
+	});
+
+	test('props: href is not empty', async () => {
+		const instance = new KBreadcrumbItem({
+			target: host,
+			props: {
+				href: 'https://github.com/ikun-svelte/ikun-ui'
+			}
+		});
+		expect(instance).toBeTruthy();
+		expect((host as HTMLElement)!.innerHTML.includes('k-breadcrumb-item-link')).toBeTruthy();
+		expect(host.querySelector('a')?.getAttribute('href')).toBe(
+			'https://github.com/ikun-svelte/ikun-ui'
+		);
+		expect(host.innerHTML).matchSnapshot();
+	});
+});

components/BreadcrumbItem/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "@ikun-ui/breadcrumb-item",
+	"version": "0.0.9-beta.2",
+	"type": "module",
+	"main": "dist/index.js",
+	"module": "dist/index.js",
+	"svelte": "dist/index.js",
+	"types": "src/index.ts",
+	"keywords": [
+		"svelte",
+		"svelte3",
+		"web component",
+		"component",
+		"react",
+		"vue",
+		"svelte-kit",
+		"dx"
+	],
+	"scripts": {
+		"build": "npm run build:js && npm run build:svelte",
+		"build:js": "tsc -p . --outDir dist/ --rootDir src/",
+		"build:svelte": "svelte-strip strip src/ dist",
+		"publish:npm": "pnpm publish --no-git-checks --access public"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@ikun-ui/icon": "workspace:*",
+		"@ikun-ui/utils": "workspace:*",
+		"baiwusanyu-utils": "^1.0.14"
+	},
+	"devDependencies": {
+		"@tsconfig/svelte": "^5.0.0",
+		"svelte-strip": "^2.0.0",
+		"tslib": "^2.6.1",
+		"typescript": "^5.1.6"
+	}
+}

components/BreadcrumbItem/src/index.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+	import { getContext } from 'svelte';
+	import { KIcon } from '@ikun-ui/icon';
+	import { getPrefixCls, createCls, BreadcrumbKey } from '@ikun-ui/utils';
+
+	export let href: string = '';
+	export let cls: string = '';
+	export let attrs: Record<string, string> = {};
+
+	const breadcrumbProps = getContext(BreadcrumbKey) || {};
+	const { separator = '/', separatorIcon = '' } = breadcrumbProps;
+
+	// class names
+	const prefixCls = getPrefixCls('breadcrumb-item');
+	$: itemCls = createCls(prefixCls, cls);
+	$: linkCls = createCls(`${prefixCls}-content`, `${prefixCls}-content__dark`, {
+		[`${prefixCls}-link`]: !!href
+	});
+	$: separatorCls = createCls(`${prefixCls}-separator`, `${prefixCls}-separator__dark`);
+</script>
+
+<span class={itemCls} {...$$restProps} {...attrs}>
+	<svelte:element this={href ? 'a' : 'span'} class={linkCls} {href}>
+		<slot />
+	</svelte:element>
+	{#if separatorIcon}
+		<KIcon cls={separatorCls} icon={separatorIcon} width="14px" height="14px"></KIcon>
+	{:else}
+		<span class={separatorCls}>{separator}</span>
+	{/if}
+</span>

components/BreadcrumbItem/src/index.ts

@@ -0,0 +1,5 @@
+/// <reference types="./types" />
+import BreadcrumbItem from './index.svelte';
+export { BreadcrumbItem as KBreadcrumbItem };
+
+export default BreadcrumbItem;

components/BreadcrumbItem/src/types.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="svelte" />
+export type KBreadcrumbItemProps = {
+	href: string;
+	cls: string;
+	attrs: Record<string, string>;
+};

components/BreadcrumbItem/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"extends": "@tsconfig/svelte/tsconfig.json",
+
+	"compilerOptions": {
+		"noImplicitAny": true,
+		"strict": true,
+		"declaration": true
+	},
+	"include": ["src/**/*.ts", "src/**/*.svelte"],
+	"exclude": ["node_modules/*", "**/*.spec.ts"]
+}

docs/.vitepress/config.ts

@@ -66,6 +66,16 @@ const components = [
 			}
 		]
 	},
+	{
+		text: 'Navigation',
+		collapsed: false,
+		items: [
+			{
+				text: 'Breadcrumb',
+				link: '/components/KBreadcrumb'
+			}
+		]
+	},
 	{
 		text: 'Feedback',
 		collapsed: false,

docs/components/KBreadcrumb.md

@@ -0,0 +1,67 @@
+---
+title: KBreadcrumb
+lang: en-US
+---
+
+# KBreadcrumb
+
+Displays the location of the current page, making it easier to browser back.
+
+## Install
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @ikun-ui/breadcrumb @ikun-ui/breadcrumb-item
+```
+
+```bash [yarn]
+yarn add @ikun-ui/breadcrumb @ikun-ui/breadcrumb-item
+```
+
+```bash [npm]
+npm install @ikun-ui/breadcrumb @ikun-ui/breadcrumb-item
+```
+
+:::
+
+## Basic usage
+
+In `KBreadcrumb`, each `KBreadcrumbItem` is a tag that stands for every level starting from homepage. This component has a String attribute `separator`, and it determines the `separator`. Its default value is '/'.
+
+<demo src="../../../../example/breadcrumb/basic.svelte"  github='Breadcrumb'></demo>
+
+## Icon separator
+
+Set `separatorIcon` to use `KIcon` as the separator, it will cover `separator`.
+
+<demo src="../../../../example/breadcrumb/separator-icon.svelte"  github='Breadcrumb'></demo>
+
+## Breadcrumb Props
+
+| Name          | Type     | Default | Description                                                |
+| ------------- | -------- | ------- | ---------------------------------------------------------- |
+| separator     | `string` | `/`     | separator character                                        |
+| separatorIcon | `string` | `''`    | The class name of the icon, following the unocss standard. |
+| cls           | `string` | `''`    | Additional class for                                       |
+| attrs         | `any`    | `{}`    | Additional attributes                                      |
+
+## Breadcrumb Slots
+
+| Name    | Description               |
+| ------- | ------------------------- |
+| default | Customize default content |
+
+## BreadcrumbItem Props
+
+| Name  | Type     | Default | Description                                                                                                                                                |
+| ----- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| href  | `string` | `''`    | The URL that the hyperlink points to, same as [href <span class="i-carbon-link text-12px" />](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) |
+| cls   | `string` | `''`    | Additional class for                                                                                                                                       |
+| attrs | `any`    | `{}`    | Additional attributes                                                                                                                                      |
+
+## BreadcrumbItem Slots
+
+| Name    | Description               |
+| ------- | ------------------------- |
+| default | Customize default content |

docs/example/breadcrumb/basic.svelte

@@ -0,0 +1,9 @@
+<script>
+	import { KBreadcrumb } from '@ikun-ui/breadcrumb';
+	import { KBreadcrumbItem } from '@ikun-ui/breadcrumb-item';
+</script>
+
+<KBreadcrumb separator=">">
+	<KBreadcrumbItem href="/">IKun UI</KBreadcrumbItem>
+	<KBreadcrumbItem>Breadcrumb</KBreadcrumbItem>
+</KBreadcrumb>

docs/example/breadcrumb/separator-icon.svelte

@@ -0,0 +1,9 @@
+<script>
+	import { KBreadcrumb } from '@ikun-ui/breadcrumb';
+	import { KBreadcrumbItem } from '@ikun-ui/breadcrumb-item';
+</script>
+
+<KBreadcrumb separatorIcon="i-carbon:arrow-right">
+	<KBreadcrumbItem href="/">IKun UI</KBreadcrumbItem>
+	<KBreadcrumbItem>Breadcrumb</KBreadcrumbItem>
+</KBreadcrumb>