Update documentation

.github/workflows/pull_requests.yml

@@ -5,11 +5,11 @@ on:
   push:
     branches: [main]
     paths:
-      - "src/**"
+      - "apps/**"
   pull_request:
     branches: [main]
     paths:
-      - "src/**"
+      - "apps/**"
 
 jobs:
   quality:

apps/docs/README.md

@@ -1,3 +1,20 @@
 # @devhaven/unit-conversion Documentation
 
-This is the documentation site for the `@devhaven/unit-conversion` package built with [Astro](https://astro.build/) using [Starlight Rapide](https://starlight.astro.build/resources/themes/) as the documentation theme.
+This is the documentation site for the `@devhaven/unit-conversion` package built with [Astro](https://astro.build/) using [Starlight Rapide](https://starlight.astro.build/resources/themes/) as the documentation theme.
+
+## Development
+
+To start the development server, run:
+
+```bash
+bun run dev
+```
+
+Then open your browser and navigate to [http://localhost:4321](http://localhost:4321).
+
+### Libraries Used
+
+- [Astro](https://astro.build/)
+- [Starlight Rapide](https://starlight.astro.build/resources/themes/)
+- [Expressive Code](https://expressive-code.com/)
+- [Expressive Code Twoslash](https://twoslash.matthiesen.dev/)

apps/docs/astro.config.mjs

@@ -1,7 +1,6 @@
-// @ts-check
-
 import starlight from "@astrojs/starlight";
 import { defineConfig } from "astro/config";
+
 import starlightThemeRapide from "starlight-theme-rapide";
 
 // https://astro.build/config
@@ -10,6 +9,9 @@ export default defineConfig({
     starlight({
       title: "Unit Conversion",
       plugins: [starlightThemeRapide()],
+      expressiveCode: {
+        // Look at ec.config.mjs instead
+      },
       social: [{ icon: "github", label: "GitHub", href: "https://github.com/BlankRiser/unit-conversion" }],
       sidebar: [
         // {

apps/docs/ec.config.mjs

@@ -0,0 +1,18 @@
+import { defineEcConfig } from "astro-expressive-code";
+import ecTwoSlash from "expressive-code-twoslash";
+
+export default defineEcConfig({
+  // Example: Using a custom plugin (which makes this `ec.config.mjs` file necessary)
+  plugins: [
+    ecTwoSlash({
+      explicitTrigger: true,
+      includeJsDoc: true,
+      allowNonStandardJsDocTags: false,
+      languages: ["ts", "tsx"],
+      twoslashOptions: {},
+    }),
+  ],
+  themes: ["andromeeda", "solarized-light"],
+
+  // ... any other options you want to configure
+});

apps/docs/package.json

@@ -11,7 +11,9 @@
   },
   "dependencies": {
     "@astrojs/starlight": "^0.35.2",
+    "@devhaven/unit-conversion": "0.0.6",
     "astro": "^5.6.1",
+    "expressive-code-twoslash": "0.5.3",
     "sharp": "^0.34.2",
     "starlight-package-managers": "0.11.0",
     "starlight-theme-rapide": "0.5.1"

apps/docs/src/content/docs/api-reference.mdx

@@ -4,7 +4,7 @@ title: "API Reference"
 
 # Conversion
 
-```ts
+```ts twoslash
 import { Conversion } from "@devhaven/unit-conversion";
 
 const conversion = new Conversion();
@@ -19,7 +19,7 @@ const result = conversion.value(10).from("meter").to("foot");
 - Default: 2
 - Number of decimal places to round the conversion result to.
 
-```ts
+```ts twoslash
 import { Conversion } from "@devhaven/unit-conversion";
 
 const conversion = new Conversion({ decimals: 4 });
@@ -32,8 +32,22 @@ const result = conversion.value(10).from("meter").to("foot");
 - Default: false
 - If true, the conversion result will be a floating-point number.
 
+```ts twoslash
+import { Conversion } from "@devhaven/unit-conversion";
+
+const conversion = new Conversion({ isFloat: true });
+const result = conversion.value(10).from("meter").to("foot");
+```
+
 ##### includeUnit?: boolean
 
 - Optional
 - Default: false
 - If true, the conversion result will include the unit as a string.
+
+```ts twoslash
+import { Conversion } from "@devhaven/unit-conversion";
+
+const conversion = new Conversion({ includeUnit: false });
+const result = conversion.value(10).from("meter").to("foot");
+```

apps/docs/src/content/docs/conversions/length.mdx

@@ -14,8 +14,8 @@ This category is useful for engineering, construction, design, or any domain whe
 
 ## Quick Example
 
-```ts
-import { Conversion } from "unit-conversion-lib";
+```ts twoslash
+import { Conversion } from "@devhaven/unit-conversion";
 
 const convert = new Conversion();
 
@@ -31,61 +31,63 @@ console.log(convert.value(1).from("inch").to("centimeter"));
 ## Common Conversions
 
 All conversions are approximate to the configured decimal precision.
-When `includeUnit` is false, only numeric values are returned.
-```ts
+
+```ts twoslash
+import { Conversion } from "@devhaven/unit-conversion";
+
 const convert = new Conversion({ includeUnit: false });
-convert.value(1).from("meter").to("foot"); // 3.28
+convert.value(1).from("meter").to("foot");      // 3.28
 ```
 
-> SI units are exact; conversions involving Imperial/US units are approximations due to defined ratios.
+> SI units are exact; conversions **involving** Imperial/US units are approximations due to defined ratios.
 
 ### Meters ↔ Kilometers
 
 ```ts
-convert.value(1000).from("meter").to("kilometer"); // "1km"
-convert.value(2).from("kilometer").to("meter"); // "2000m"
+convert.value(1000).from("meter").to("kilometer");      // "1km"
+convert.value(2).from("kilometer").to("meter");         // "2000m"
 ```
 
 ### Meters ↔ Feet
 
 ```ts
-convert.value(1).from("meter").to("foot"); // "3.28ft"
-convert.value(10).from("foot").to("meter"); // "3.05m"
+convert.value(1).from("meter").to("foot");      // "3.28ft"
+convert.value(10).from("foot").to("meter");     // "3.05m"
 ```
 
 ### Inches ↔ Centimeters
 
 ```ts
-convert.value(1).from("inch").to("centimeter"); // "2.54cm"
-convert.value(30).from("centimeter").to("inch"); // "11.81in"
+convert.value(1).from("inch").to("centimeter");      // "2.54cm"
+convert.value(30).from("centimeter").to("inch");     // "11.81in"
 ```
 
 ### Miles ↔ Kilometers
 
 ```ts
-convert.value(1).from("mile").to("kilometer"); // "1.609km"
-convert.value(5).from("kilometer").to("mile"); // "3.11mi"
+convert.value(1).from("mile").to("kilometer");      // "1.609km"
+convert.value(5).from("kilometer").to("mile");      // "3.11mi"
 ```
 
 ### Yards ↔ Meters
 
 ```ts
-convert.value(1).from("yard").to("meter"); // "0.914m"
-convert.value(50).from("meter").to("yard"); // "54.68yd"
+convert.value(1).from("yard").to("meter");      // "0.914m"
+convert.value(50).from("meter").to("yard");     // "54.68yd"
 ```
 
-
 ## Configuration Options
 
 Conversions can be customized with global config values when creating a Conversion instance.
 
-```ts
+```ts twoslash
+import { Conversion } from "@devhaven/unit-conversion";
+
 const convert = new Conversion({
-  decimals: 4,      // set precision
-  isFloat: true,    // keep decimals or round
-  includeUnit: true // whether to append unit symbol
+  decimals: 4,       // set precision
+  isFloat: true,     // keep decimals or round
+  includeUnit: true, // whether to append unit symbol
 });
 
-console.log(convert.value(1).from("mile").to("kilometer"));
-// "1.6093km"
-```
+console.log(convert.value(1).from("mile").to("kilometer"));      // "1.6093km"
+```

apps/docs/src/content/docs/conversions/number.mdx

@@ -14,16 +14,27 @@ The **Number** category supports conversions between number bases such as binary
 
 ## Quick Example
 ```ts
-console.log(convert.value(255).from("decimal").to("hexadecimal")); 
-// "ff"
+console.log(convert.value(255).from("decimal").to("hexadecimal"));    // "ff"
 
-console.log(convert.value("1010").from("binary").to("decimal")); 
-// "10"
+console.log(convert.value("1010").from("binary").to("decimal"));      // "10"
 ```
 
 ## Common Conversions
+
+### Binary ↔ Decimal
 ```ts
 convert.value(10).from("decimal").to("binary");      // "1010"
-convert.value("a").from("hexadecimal").to("decimal"); // "10"
-convert.value("77").from("octal").to("decimal");      // "63"
+convert.value(10).from("binary").to("decimal");      // "1010"
+```
+
+### Decimal ↔ Hexadecimal
+```ts
+convert.value("a").from("hexadecimal").to("decimal");     // "10"
+convert.value(15).from("decimal").to("hexadecimal");      // "f"
+```
+
+### Octal ↔ Decimal
+```ts
+convert.value(77).from("octal").to("decimal");      // "63"
+convert.value(77).from("decimal").to("octal");      // "115"
 ```

apps/docs/src/content/docs/conversions/temperature.mdx

@@ -14,17 +14,22 @@ The Temperature category supports conversions between Celsius, Fahrenheit, and K
 ## Quick Example
 
 ```ts
-console.log(convert.value(0).from("celsius").to("fahrenheit")); 
-// "32°F"
+console.log(convert.value(0).from("celsius").to("fahrenheit"));      // "32°F"
 
-console.log(convert.value(212).from("fahrenheit").to("celsius")); 
-// "100°C"
+console.log(convert.value(212).from("fahrenheit").to("celsius"));    // "100°C"
 ```
 
 ## Common Conversions
 
+
+### Celsius ↔ Kelvin
+```ts
+convert.value(100).from("celsius").to("kelvin");    // "373.15K"
+convert.value(0).from("kelvin").to("celsius");      // "-273.15°C"
+```
+
+### Celsius ↔ Fahrenheit
 ```ts
-convert.value(1).from("day").to("hour");              // "24h"
-convert.value(3600).from("second").to("hour");        // "1h"
-convert.value(1000).from("millisecond").to("second"); // "1s"
+convert.value(100).from("celsius").to("fahrenheit");     // "212°F"
+convert.value(32).from("fahrenheit").to("celsius");      // "0°C"
 ```

apps/docs/src/content/docs/conversions/time.mdx

@@ -2,3 +2,45 @@
 title: "Time"
 template: doc
 ---
+The **time** category provides conversions between milliseconds, seconds, minutes, hours, and days.
+
+## Supported Units
+
+- millisecond (ms)
+- second (s)
+- minute (min)
+- hour (h)
+- day (d)
+
+## Quick Example
+
+```ts twoslash
+import { Conversion } from "@devhaven/unit-conversion";
+
+const convert = new Conversion();
+console.log(convert.value(60000).from("millisecond").to("minute"));      // "1min"
+console.log(convert.value(2).from("hour").to("minute"));                 // "120min"
+```
+
+## Common Conversions
+
+### Day ↔ Hour
+
+```ts
+convert.value(1).from("day").to("hour");        // "24h"
+convert.value(24).from("hour").to("day");       // "1d"
+```
+
+### Second ↔ Hour
+
+```ts
+convert.value(3600).from("second").to("hour");      // "1h"
+convert.value(1).from("hour").to("second");         // "3600s"
+```
+
+### Millisecond ↔ Second
+
+```ts
+convert.value(1000).from("millisecond").to("second");      // "1s"
+convert.value(1).from("second").to("millisecond");         // "1000ms"
+```

apps/docs/src/content/docs/conversions/volume.mdx

@@ -19,9 +19,21 @@ console.log(convert.value(1).from("gallon").to("liter"));
 ```
 
 ## Common Conversions
+
+### Liter ↔ Milliliter
+```ts
+convert.value(1).from("liter").to("milliliter");      // "1000ml"
+convert.value(1).from("milliliter").to("liter");      // "0.001l"
+```
+
+### Liter ↔ Cubic Meter
+```ts
+convert.value(1).from("liter").to("cubic-meter");      // "0.001m^3"
+convert.value(1).from("cubic-meter").to("liter");      // "1000l"
+```
+
+### Cup (US) ↔ Milliliter
 ```ts
-convert.value(1).from("liter").to("milliliter"); // "1000ml"
-convert.value(1).from("liter").to("quart");      // "1.057qt"
-convert.value(1).from("pint").to("cup");         // "2cup"
-convert.value(1).from("gallon").to("quart");     // "4qt"
+convert.value(1).from("us-legal-cup").to("milliliter");      // "236.5882ml"
+convert.value(1).from("milliliter").to("us-legal-cup");      // "0.0042cup (US)"
 ```