new base docs on foundation classes

Author: matas-bitbybit-dev

docs/learn/code/common/base/color/_category_.json

@@ -0,0 +1,10 @@
+{
+    "label": "Color",
+    "position": 2,
+    "link": {
+        "type": "generated-index",
+        "title": "Colors in Bitbybit",
+        "description": "Introduction to colors in Bitbybit.",
+        "slug": "/code/common/base/color"
+    }
+}

docs/learn/code/common/base/color/intro.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 1
+title: Colors in Bitbybit
+sidebar_label: Colors in Bitbybit
+description: An overview of the Color class in Bitbybit, explaining how to work with hex and RGB color formats, convert between them, and perform basic color manipulations.
+tags: [code, color]
+---
+
+<img 
+  src="https://s.bitbybit.dev/assets/icons/white/color-icon.svg" 
+  alt="Color category icon" 
+  title="Color category icon"
+  width="100" /> 
+
+[View Full Source & Details on GitHub](https://github.com/bitbybit-dev/bitbybit/blob/master/packages/dev/base/lib/api/services/color.ts)
+
+The `Color` class in Bitbybit provides tools for defining, converting, and manipulating colors, primarily focusing on hexadecimal (hex) and RGB (Red, Green, Blue) color formats.
+
+**Understanding Color Formats in Bitbybit:**
+
+*   **Hex Color (`Inputs.Base.Color`):** This is a string representation of a color, commonly used in web design and graphics, like `#FF0000` (for red) or `#00FF00` (for green).
+*   **RGB Color (`Inputs.Base.ColorRGB`):** This is an object representing color with separate red, green, and blue components, typically as numbers. For example, `{ r: 255, g: 0, b: 0 }` for red.
+    *   The `Color` class can handle RGB values in different ranges (e.g., 0-255, 0-1, or 0-100) and will remap them as needed for conversions.
+
+## Core Capabilities of the Color Class
+
+The `Color` class makes it easy to work with these common color formats. Here's what it can do. For precise input parameters and detailed behavior (like how RGB ranges are handled), please consult the [full Color API documentation](https://docs.bitbybit.dev/classes/Bit.Color.html) or the GitHub source linked above.
+
+### 1. Creating and Representing Colors
+
+*   **Hex Color Input (`hexColor()`):** If you already have a hex color string (e.g., from a color picker), this function simply returns it. It's useful in visual programming environments to explicitly define a color input.
+
+### 2. Converting Between Color Formats
+
+This is a key function of the class, allowing you to switch between hex and RGB representations:
+*   **Hex to RGB (`hexToRgb()`):** Converts a hex color string (e.g., `#FF0000`) into an RGB object (e.g., `{ r: 255, g: 0, b: 0 }`).
+*   **Hex to RGB Mapped (`hexToRgbMapped()`):** Converts a hex color to an RGB object, but then remaps the R, G, and B values from the standard 0-255 range to a custom range you specify (e.g., 0-1).
+*   **RGB to Hex (`rgbToHex()`):** Converts individual R, G, and B numerical values into a hex color string. It can intelligently handle input RGB values that are not in the 0-255 range by remapping them if you provide their original `min` and `max` range.
+*   **RGB Object to Hex (`rgbObjToHex()`):** Similar to `rgbToHex()`, but takes an RGB object (`{r, g, b}`) as input instead of separate R, G, B parameters.
+
+### 3. Extracting Color Components
+
+Get individual R, G, or B values from a color:
+*   **From Hex (Mapped):**
+    *   `getRedParam()`: Gets the red component from a hex color, remapped to a specified range.
+    *   `getGreenParam()`: Gets the green component from a hex color, remapped to a specified range.
+    *   `getBlueParam()`: Gets the blue component from a hex color, remapped to a specified range.
+*   **From RGB Object:**
+    *   `rgbToRed()`: Extracts the `r` value from an RGB object.
+    *   `rgbToGreen()`: Extracts the `g` value from an RGB object.
+    *   `rgbToBlue()`: Extracts the `b` value from an RGB object.
+
+### 4. Basic Color Manipulation
+
+*   **Invert Color (`invert()`):**
+    *   Takes a hex color and produces its photographic negative (e.g., red becomes cyan, white becomes black).
+    *   It also offers an option to invert to pure black or white based on the original color's perceived brightness, which can be useful for ensuring text visibility against a colored background.

docs/learn/code/common/base/dates/_category_.json

@@ -0,0 +1,10 @@
+{
+    "label": "Dates",
+    "position": 2,
+    "link": {
+        "type": "generated-index",
+        "title": "Dates in Bitbybit",
+        "description": "Introduction to dates in Bitbybit.",
+        "slug": "/code/common/base/dates"
+    }
+}

docs/learn/code/common/base/dates/intro.md

@@ -0,0 +1,78 @@
+---
+sidebar_position: 1
+title: Dates in Bitbybit
+sidebar_label: Dates in Bitbybit
+description: An overview of the Dates class in Bitbybit, explaining how to create, access, modify, and format date and time information.
+tags: [code, dates]
+---
+
+<img 
+  src="https://s.bitbybit.dev/assets/icons/white/dates-icon.svg" 
+  alt="Dates category icon" 
+  title="Dates category icon"
+  width="100" /> 
+
+[View Full Source & Details on GitHub](https://github.com/bitbybit-dev/bitbybit/blob/master/packages/dev/base/lib/api/services/dates.ts)
+
+The `Dates` class in Bitbybit provides a collection of tools for working with dates and times. It largely leverages the built-in JavaScript `Date` object, offering convenient methods to create, manipulate, and query date information.
+
+**What is a Date in Bitbybit?**
+
+A "Date" in Bitbybit refers to a standard JavaScript `Date` object. This object encapsulates a specific moment in time, including the year, month, day, hour, minute, second, and millisecond.
+
+## Core Capabilities of the Dates Class
+
+The `Dates` class simplifies common date and time operations. Here's a high-level look at its features. For the exact input parameters (like DTOs) and detailed behavior (e.g., how months are 0-indexed), please consult the [full Dates API documentation](https://docs.bitbybit.dev/classes/Bit.Dates.html) or the GitHub source linked above.
+
+### 1. Creating Dates
+
+Need to define a specific date or get the current time?
+*   **Current Date & Time (`now()`):** Get a `Date` object representing the exact moment the function is called.
+*   **Specific Date (`createDate()`):** Create a `Date` object by providing individual components like year, month (0-11), day, hours, minutes, seconds, and milliseconds.
+*   **Specific UTC Date (`createDateUTC()`):** Similar to `createDate()`, but interprets the provided components as Coordinated Universal Time (UTC).
+*   **From Timestamp (`createFromUnixTimeStamp()`):** Create a `Date` object from a Unix timestamp (the number of milliseconds since January 1, 1970, UTC).
+
+### 2. Converting Dates to Strings (Formatting)
+
+Displaying dates in a human-readable format:
+*   **Basic String (`toString()`):** Get a general string representation of the date (format depends on the system's locale).
+*   **Date Part Only (`toDateString()`):** Get just the date portion as a string (e.g., "Mon Jan 01 2024").
+*   **Time Part Only (`toTimeString()`):** Get just the time portion as a string (e.g., "14:30:00 GMT+0000").
+*   **ISO Format (`toISOString()`):** Get the date in the standard ISO 8601 format (e.g., "2024-01-01T14:30:00.000Z"). This is often used for data interchange.
+*   **JSON Format (`toJSON()`):** Get the date as a string suitable for JSON serialization (typically ISO format).
+*   **UTC String (`toUTCString()`):** Get the date as a string formatted according to UTC conventions (e.g., "Mon, 01 Jan 2024 14:30:00 GMT").
+
+### 3. Getting Specific Parts of a Date
+
+Extracting individual components from a `Date` object. Most "get" methods have both a local time version and a UTC version:
+*   **Year:** `getYear()` / `getUTCYear()`
+*   **Month:** `getMonth()` (0 for January, 11 for December) / `getUTCMonth()`
+*   **Day of the Month:** `getDayOfMonth()` (1-31) / `getUTCDay()` (Note: `getUTCDay()` in JS Date returns day of week for UTC, but here it seems to mean day of month for UTC based on pairing with `setUTCDay` which takes day of month).
+*   **Day of the Week:** `getWeekday()` (0 for Sunday, 6 for Saturday - local time)
+*   **Hours:** `getHours()` (0-23) / `getUTCHours()`
+*   **Minutes:** `getMinutes()` (0-59) / `getUTCMinutes()`
+*   **Seconds:** `getSeconds()` (0-59) / `getUTCSeconds()`
+*   **Milliseconds:** `getMilliseconds()` (0-999) / `getUTCMilliseconds()`
+*   **Total Time (`getTime()`):** Get the raw numeric value of the date, represented as milliseconds since the Unix epoch (January 1, 1970, UTC).
+
+### 4. Setting Parts of a Date (Modifying Dates)
+
+Changing components of an existing `Date` object. These methods typically return a *new* `Date` object with the modification, leaving the original unchanged. Like "get" methods, "set" methods often have local and UTC versions:
+*   **Year:** `setYear()` / `setUTCYear()`
+*   **Month:** `setMonth()` / `setUTCMonth()`
+*   **Day of the Month:** `setDayOfMonth()` / `setUTCDay()`
+*   **Hours:** `setHours()` / `setUTCHours()`
+*   **Minutes:** `setMinutes()` / `setUTCMinutes()`
+*   **Seconds:** `setSeconds()` / `setUTCSeconds()`
+*   **Milliseconds:** `setMilliseconds()` / `setUTCMilliseconds()`
+*   **Total Time (`setTime()`):** Set the date based on a Unix timestamp (milliseconds since epoch).
+
+### 5. Parsing Date Strings
+
+*   **Parse Date String (`parseDate()`):** Convert a string representation of a date into a Unix timestamp (number of milliseconds since epoch). The success of parsing depends on the format of the string and the browser's parsing capabilities.
+
+## Important Notes:
+
+*   **Local Time vs. UTC:** Be mindful of whether you're working with local time (which depends on the user's system timezone) or UTC (a global time standard). The class provides methods for both.
+*   **Month Indexing:** When creating dates or getting/setting months, remember that months are typically 0-indexed in JavaScript (0 for January, 1 for February, ..., 11 for December).
+*   **Immutability:** The "set" methods in this class are designed to be immutable: they return a *new* `Date` object with the changes, rather than modifying the original `Date` object you passed in. This is generally a safer approach.

docs/learn/code/common/base/line/_category_.json

@@ -0,0 +1,10 @@
+{
+    "label": "Line",
+    "position": 2,
+    "link": {
+        "type": "generated-index",
+        "title": "Lines in Bitbybit",
+        "description": "Introduction to lines in Bitbybit.",
+        "slug": "/code/common/base/line"
+    }
+}

docs/learn/code/common/base/line/intro.md

@@ -0,0 +1,67 @@
+---
+title: Lines in Bitbybit
+sidebar_label: Lines in Bitbybit
+description: An overview of the Line class in Bitbybit, explaining how to create, analyze, and transform lines and line segments in 3D.
+tags: [code, line]
+---
+
+<img 
+  src="https://s.bitbybit.dev/assets/icons/white/line-icon.svg" 
+  alt="Line category icon" 
+  title="Line category icon"
+  width="100" /> 
+
+[View Full Source & Details on GitHub](https://github.com/bitbybit-dev/bitbybit/blob/master/packages/dev/base/lib/api/services/line.ts)
+
+The `Line` class in Bitbybit provides tools for working with straight lines and line segments in 3D space.
+
+**What is a Line in Bitbybit?**
+
+In Bitbybit, a "Line" (specifically, a line segment) is typically defined by two points: a start point and an end point. It's represented as an object:
+`{ start: [x, y, z], end: [x, y, z] }`
+
+Sometimes, a "segment" might also be represented as a simple array of two points:
+`[[startX, startY, startZ], [endX, endY, endZ]]`
+
+The `Line` class provides methods to work with both these representations and convert between them.
+
+## Core Capabilities of the Line Class
+
+The `Line` class allows you to define, analyze, and manipulate these line segments. Here's a high-level look at its features. For the exact input parameters (like DTOs) and detailed behavior, please refer to the [full Line API documentation](https://docs.bitbybit.dev/classes/Bit.Line.html) or the GitHub source linked above.
+
+### 1. Creating Lines and Segments
+
+Defining new lines:
+*   **From Start and End Points (`create()`):** Create a line object `{ start, end }` by providing its two endpoint coordinates.
+*   **Segment from Points (`createSegment()`):** Create a segment (an array of two points) from its start and end point coordinates.
+*   **Lines from a Sequence of Points (`linesBetweenPoints()`):** Given a list of points, create a series of connected line segments (e.g., point A to B, B to C, C to D).
+*   **Lines from Separate Start/End Point Lists (`linesBetweenStartAndEndPoints()`):** If you have a list of start points and a corresponding list of end points, create a line segment for each pair.
+
+### 2. Getting Information About Lines
+
+Accessing properties of a line:
+*   **Endpoints:** Get the start point (`getStartPoint()`) or end point (`getEndPoint()`) of a line.
+*   **Length (`length()`):** Calculate the length of a line segment.
+*   **Point on Line (`getPointOnLine()`):** Find the coordinates of a point that lies on the line segment at a specific fractional distance (parameter `param` from 0.0 at the start to 1.0 at the end) between its start and end points.
+
+### 3. Modifying and Transforming Lines
+
+Changing existing lines:
+*   **Reverse (`reverse()`):** Swap the start and end points of a line.
+*   **Transformations:**
+    *   `transformLine()`: Apply a 3D transformation (like translation, rotation, scaling) to a single line.
+    *   `transformsForLines()`: Apply a unique transformation to each line in a list of lines.
+
+### 4. Converting Between Line and Segment Formats
+
+Switching representations:
+*   **Line to Segment (`lineToSegment()`, `linesToSegments()`):** Convert a line object (or a list of them) into the segment array format.
+*   **Segment to Line (`segmentToLine()`, `segmentsToLines()`):** Convert a segment array (or a list of them) into the line object format.
+
+### 5. Intersection (Advanced)
+
+*   **Line-Line Intersection (`lineLineIntersection()`):**
+    *   Determine if two lines (or line segments, if specified) intersect in 3D space.
+    *   If they do intersect, this method returns the point of intersection.
+    *   It handles various cases, including parallel, collinear, and skew lines, using a tolerance value.
+    *   You can specify whether to check for intersection only within the bounds of the line *segments* or to treat them as infinite lines.

docs/learn/code/common/base/lists/_category_.json

@@ -0,0 +1,10 @@
+{
+    "label": "Lists",
+    "position": 2,
+    "link": {
+        "type": "generated-index",
+        "title": "Lists in Bitbybit",
+        "description": "Introduction to lists in Bitbybit.",
+        "slug": "/code/common/base/lists"
+    }
+}