@pikacss/plugin-typography 0.0.47 → 0.0.48

package/README.md

@@ -0,0 +1,37 @@
+# @pikacss/plugin-typography
+
+Typography plugin for PikaCSS. Provides `prose` shortcuts for styling long-form content.
+
+## Installation
+
+```bash
+pnpm add -D @pikacss/plugin-typography
+```
+
+## Usage
+
+```ts
+import { defineEngineConfig } from '@pikacss/core'
+import { typography } from '@pikacss/plugin-typography'
+
+export default defineEngineConfig({
+  plugins: [typography()],
+})
+```
+
+Then use in templates:
+
+```vue
+<article :class="pika('prose')">
+  <h1>Title</h1>
+  <p>Content with beautiful typography.</p>
+</article>
+```
+
+## Documentation
+
+See the [full documentation](https://pikacss.com/guide/plugins/typography).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,6 +1,23 @@
 import { EnginePlugin } from "@pikacss/core";
 
 //#region src/styles.d.ts
+/**
+ * Default CSS custom property values for prose typography colors and accents.
+ * @internal
+ *
+ * @remarks Each variable controls a specific color role within prose content
+ * (body text, headings, links, code, borders, etc.). All default to
+ * `currentColor` or `transparent`, allowing consumers to override them
+ * through the plugin's `variables` option.
+ *
+ * @example
+ * ```ts
+ * engine.variables.add({
+ *   ...typographyVariables,
+ *   '--pk-prose-color-links': '#3b82f6',
+ * })
+ * ```
+ */
 declare const typographyVariables: {
   '--pk-prose-color-body': string;
   '--pk-prose-color-headings': string;
@@ -23,17 +40,62 @@ declare const typographyVariables: {
 };
 //#endregion
 //#region src/index.d.ts
+/**
+ * Configuration options for the typography plugin.
+ *
+ * @remarks Pass this object under the `typography` key in your engine config
+ * to customize prose color variables.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   typography: {
+ *     variables: { '--pk-prose-color-links': '#3b82f6' },
+ *   },
+ * }
+ * ```
+ */
 interface TypographyPluginOptions {
   /**
-   * Custom variables to override the default typography variables.
+   * Partial overrides for the default prose CSS custom properties.
+   *
+   * @default `{}`
    */
   variables?: Partial<typeof typographyVariables>;
 }
 declare module '@pikacss/core' {
   interface EngineConfig {
+    /**
+     * Typography plugin options forwarded from the engine config.
+     *
+     * @default `undefined`
+     */
     typography?: TypographyPluginOptions;
   }
 }
+/**
+ * Creates the PikaCSS typography engine plugin.
+ *
+ * @returns An engine plugin that registers prose CSS variables and shortcut
+ * utilities (`prose`, `prose-sm`, `prose-lg`, `prose-xl`, `prose-2xl`).
+ *
+ * @remarks The plugin reads the `typography` key from the engine config,
+ * merges user-provided variable overrides with the defaults, and registers
+ * a full set of typography shortcuts covering paragraphs, links, headings,
+ * lists, code, tables, and more.
+ *
+ * @example
+ * ```ts
+ * import { typography } from '@pikacss/plugin-typography'
+ *
+ * export default defineEngineConfig({
+ *   plugins: [typography()],
+ *   typography: {
+ *     variables: { '--pk-prose-color-links': '#3b82f6' },
+ *   },
+ * })
+ * ```
+ */
 declare function typography(): EnginePlugin;
 //#endregion
 export { TypographyPluginOptions, typography };

package/dist/index.mjs

@@ -1,6 +1,22 @@
 import { defineEnginePlugin, defineStyleDefinition } from "@pikacss/core";
-
 //#region src/styles.ts
+/**
+* Default CSS custom property values for prose typography colors and accents.
+* @internal
+*
+* @remarks Each variable controls a specific color role within prose content
+* (body text, headings, links, code, borders, etc.). All default to
+* `currentColor` or `transparent`, allowing consumers to override them
+* through the plugin's `variables` option.
+*
+* @example
+* ```ts
+* engine.variables.add({
+*   ...typographyVariables,
+*   '--pk-prose-color-links': '#3b82f6',
+* })
+* ```
+*/
 const typographyVariables = {
 	"--pk-prose-color-body": "currentColor",
 	"--pk-prose-color-headings": "currentColor",
@@ -21,6 +37,18 @@ const typographyVariables = {
 	"--pk-prose-color-kbd": "currentColor",
 	"--pk-prose-kbd-shadows": "currentColor"
 };
+/**
+* Base prose container styles that set color, max-width, font size, and line height.
+* @internal
+*
+* @remarks Also collapses margins on the first and last child elements to
+* prevent unwanted spacing at the edges of the prose container.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-base', proseBaseStyle])
+* ```
+*/
 const proseBaseStyle = defineStyleDefinition({
 	"color": "var(--pk-prose-color-body)",
 	"maxWidth": "65ch",
@@ -29,6 +57,18 @@ const proseBaseStyle = defineStyleDefinition({
 	"$ > :first-child": { marginTop: "0" },
 	"$ > :last-child": { marginBottom: "0" }
 });
+/**
+* Paragraph and lead-text styles for prose content.
+* @internal
+*
+* @remarks Applies vertical margins to `<p>` elements and additional size,
+* color, and spacing overrides for elements carrying the `lead` class.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-paragraphs', ['prose-base', proseParagraphsStyle]])
+* ```
+*/
 const proseParagraphsStyle = defineStyleDefinition({
 	"$ p": {
 		marginTop: "1.25em",
@@ -42,6 +82,18 @@ const proseParagraphsStyle = defineStyleDefinition({
 		marginBottom: "1.2em"
 	}
 });
+/**
+* Anchor link styles for prose content.
+* @internal
+*
+* @remarks Sets link color, underline decoration, and medium font weight.
+* Nested `<strong>` and `<code>` inside links inherit the link color.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-links', ['prose-base', proseLinksStyle]])
+* ```
+*/
 const proseLinksStyle = defineStyleDefinition({
 	"$ a": {
 		color: "var(--pk-prose-color-links)",
@@ -51,6 +103,19 @@ const proseLinksStyle = defineStyleDefinition({
 	"$ a strong": { color: "inherit" },
 	"$ a code": { color: "inherit" }
 });
+/**
+* Strong and italic emphasis styles for prose content.
+* @internal
+*
+* @remarks Bold text receives a dedicated color variable and semi-bold weight.
+* When `<strong>` appears inside links, blockquotes, or table headers the
+* color inherits from the parent to avoid clashing with contextual colors.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-emphasis', ['prose-base', proseEmphasisStyle]])
+* ```
+*/
 const proseEmphasisStyle = defineStyleDefinition({
 	"$ strong": {
 		color: "var(--pk-prose-color-bold)",
@@ -61,6 +126,18 @@ const proseEmphasisStyle = defineStyleDefinition({
 	"$ thead th strong": { color: "inherit" },
 	"$ em": { fontStyle: "italic" }
 });
+/**
+* Keyboard input (`<kbd>`) styles for prose content.
+* @internal
+*
+* @remarks Renders `<kbd>` elements with a subtle raised appearance using
+* box-shadow borders. Color and shadow are driven by dedicated CSS variables.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-kbd', ['prose-base', proseKbdStyle]])
+* ```
+*/
 const proseKbdStyle = defineStyleDefinition({ "$ kbd": {
 	color: "var(--pk-prose-color-kbd)",
 	fontSize: "0.875em",
@@ -73,6 +150,19 @@ const proseKbdStyle = defineStyleDefinition({ "$ kbd": {
 	paddingLeft: "0.375em",
 	boxShadow: "0 0 0 1px var(--pk-prose-kbd-shadows), 0 3px 0 var(--pk-prose-kbd-shadows)"
 } });
+/**
+* Ordered list, unordered list, and definition list styles for prose content.
+* @internal
+*
+* @remarks Handles list markers (decimal, alpha, roman), nested list bullet
+* progression (disc → circle → square), item spacing, and definition list
+* (`<dl>`, `<dt>`, `<dd>`) layout.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-lists', ['prose-base', proseListsStyle]])
+* ```
+*/
 const proseListsStyle = defineStyleDefinition({
 	"$ ol": {
 		listStyleType: "decimal",
@@ -129,6 +219,19 @@ const proseListsStyle = defineStyleDefinition({
 		paddingLeft: "1.625em"
 	}
 });
+/**
+* Horizontal rule (`<hr>`) styles for prose content.
+* @internal
+*
+* @remarks Applies generous vertical margins and a single-pixel top border
+* colored by the `--pk-prose-color-hr` variable. The element immediately
+* following an `<hr>` has its top margin collapsed.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-hr', ['prose-base', proseHrStyle]])
+* ```
+*/
 const proseHrStyle = defineStyleDefinition({
 	"$ hr": {
 		borderColor: "var(--pk-prose-color-hr)",
@@ -138,6 +241,20 @@ const proseHrStyle = defineStyleDefinition({
 	},
 	"$ hr + *": { marginTop: "0" }
 });
+/**
+* Heading (h1–h4) styles for prose content.
+* @internal
+*
+* @remarks Each heading level gets a distinct font size, weight, line height,
+* and vertical margin. Nested `<strong>` receives a heavier weight and
+* `<code>` inherits the heading color. Sibling elements after h2/h3/h4
+* have their top margin collapsed.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-headings', ['prose-base', proseHeadingsStyle]])
+* ```
+*/
 const proseHeadingsStyle = defineStyleDefinition({
 	"$ h1": {
 		color: "var(--pk-prose-color-headings)",
@@ -182,6 +299,19 @@ const proseHeadingsStyle = defineStyleDefinition({
 	"$ h4 code": { color: "inherit" },
 	"$ h4 + *": { marginTop: "0" }
 });
+/**
+* Blockquote styles for prose content.
+* @internal
+*
+* @remarks Renders blockquotes with italic text, a left border accent,
+* and automatic open/close curly quotes via CSS `content`. Nested
+* `<code>` inherits the quote color.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-quotes', ['prose-base', proseQuotesStyle]])
+* ```
+*/
 const proseQuotesStyle = defineStyleDefinition({
 	"$ blockquote": {
 		fontWeight: "500",
@@ -198,6 +328,19 @@ const proseQuotesStyle = defineStyleDefinition({
 	"$ blockquote p:last-of-type::after": { content: "close-quote" },
 	"$ blockquote code": { color: "inherit" }
 });
+/**
+* Image, video, picture, figure, and figcaption styles for prose content.
+* @internal
+*
+* @remarks Applies consistent vertical margins to media elements and
+* collapses inner margins within `<figure>`. Figcaptions receive a
+* smaller font size and the captions color variable.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-media', ['prose-base', proseMediaStyle]])
+* ```
+*/
 const proseMediaStyle = defineStyleDefinition({
 	"$ img": {
 		marginTop: "2em",
@@ -227,6 +370,20 @@ const proseMediaStyle = defineStyleDefinition({
 		marginTop: "0.85em"
 	}
 });
+/**
+* Inline code and preformatted code block styles for prose content.
+* @internal
+*
+* @remarks Inline `<code>` receives backtick-style pseudo-element wrappers
+* and bold weight. `<pre>` blocks get background color, rounded corners,
+* horizontal scroll, and padding. Code inside `<pre>` resets to inherit
+* parent styles and removes the backtick wrappers.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-code', ['prose-base', proseCodeStyle]])
+* ```
+*/
 const proseCodeStyle = defineStyleDefinition({
 	"$ code": {
 		color: "var(--pk-prose-color-code)",
@@ -264,6 +421,20 @@ const proseCodeStyle = defineStyleDefinition({
 	"$ pre code::before": { content: "none" },
 	"$ pre code::after": { content: "none" }
 });
+/**
+* Table, thead, tbody, and tfoot styles for prose content.
+* @internal
+*
+* @remarks Tables span the full width with auto layout. Header cells receive
+* the headings color and bottom border; body rows get per-row bottom
+* borders (removed on the last row). First and last cell padding is
+* collapsed flush with the table edges.
+*
+* @example
+* ```ts
+* engine.shortcuts.add(['prose-tables', ['prose-base', proseTablesStyle]])
+* ```
+*/
 const proseTablesStyle = defineStyleDefinition({
 	"$ table": {
 		width: "100%",
@@ -304,7 +475,6 @@ const proseTablesStyle = defineStyleDefinition({
 	"$ tbody td:first-child, $ tfoot td:first-child": { paddingLeft: "0" },
 	"$ tbody td:last-child, $ tfoot td:last-child": { paddingRight: "0" }
 });
-
 //#endregion
 //#region src/index.ts
 const proseShortcutModules = [
@@ -348,6 +518,29 @@ function registerTypographyShortcuts(engine) {
 		engine.shortcuts.add([`prose-${size}`, ["prose", overrides]]);
 	});
 }
+/**
+* Creates the PikaCSS typography engine plugin.
+*
+* @returns An engine plugin that registers prose CSS variables and shortcut
+* utilities (`prose`, `prose-sm`, `prose-lg`, `prose-xl`, `prose-2xl`).
+*
+* @remarks The plugin reads the `typography` key from the engine config,
+* merges user-provided variable overrides with the defaults, and registers
+* a full set of typography shortcuts covering paragraphs, links, headings,
+* lists, code, tables, and more.
+*
+* @example
+* ```ts
+* import { typography } from '@pikacss/plugin-typography'
+*
+* export default defineEngineConfig({
+*   plugins: [typography()],
+*   typography: {
+*     variables: { '--pk-prose-color-links': '#3b82f6' },
+*   },
+* })
+* ```
+*/
 function typography() {
 	let typographyConfig = {};
 	return defineEnginePlugin({
@@ -364,6 +557,5 @@ function typography() {
 		}
 	});
 }
-
 //#endregion
-export { typography };
+export { typography };

package/package.json

@@ -4,12 +4,13 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.47",
+  "version": "0.0.48",
   "author": "DevilTea <ch19980814@gmail.com>",
   "license": "MIT",
+  "homepage": "https://pikacss.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pikacss/pikacss.git",
+    "url": "git+https://github.com/pikacss/pikacss.git",
     "directory": "packages/plugin-typography"
   },
   "bugs": {
@@ -20,6 +21,7 @@
     "pikacss-plugin",
     "typography"
   ],
+  "sideEffects": false,
   "exports": {
     ".": {
       "import": {
@@ -33,19 +35,22 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=22"
+  },
   "peerDependencies": {
-    "@pikacss/core": "0.0.47"
+    "@pikacss/core": "0.0.48"
   },
   "devDependencies": {
-    "@pikacss/core": "0.0.47"
+    "@pikacss/core": "0.0.48"
   },
   "scripts": {
     "build": "tsdown",
-    "build:pack": "pnpm build && pnpm pack",
+    "build:watch": "tsdown --watch",
     "typecheck": "pnpm typecheck:package && pnpm typecheck:test",
     "typecheck:package": "tsc --project ./tsconfig.package.json --noEmit",
     "typecheck:test": "tsc --project ./tsconfig.tests.json --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "vitest run --config ./vitest.config.ts",
+    "test:watch": "vitest --config ./vitest.config.ts"
   }
 }