@octaviaflow/grid 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# @octaviaflow/grid
+
+> Grid for digital and software products using the Carbon Design System
+
+## Getting started
+
+To install `@octaviaflow/grid` in your project, you will need to run the following
+command using [npm](https://www.npmjs.com/):
+
+```bash
+npm install -S @octaviaflow/grid
+```
+
+If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
+instead:
+
+```bash
+yarn add @octaviaflow/grid
+```
+
+You can then include the grid by doing the following in your Sass files:
+
+```
+@use '@octaviaflow/grid';
+
+// Emit the flex-grid styles
+@include grid.flex-grid();
+```
+
+## Usage
+
+_More examples and documentation can be found on this
+[live demo website](https://carbon-elements.netlify.app/grid/examples/preview/)._
+
+`@octaviaflow/grid` has three primitive class types to use in order to structure your
+application. They include:
+
+- `cds--grid`, defines the overall grid context and sets some useful attributes
+  like width and margin
+- `cds--row`, defines a row of items in a grid
+- `cds--col`, used to define individual columns
+
+You can use a combination of these classes to build a layout. For example, if we
+wanted a 4 column layout for a small breakpoint we could use the following
+markup:
+
+```html
+<div class="cds--grid">
+  <div class="cds--row">
+    <div class="cds--col">1/4</div>
+    <div class="cds--col">1/4</div>
+    <div class="cds--col">1/4</div>
+    <div class="cds--col">1/4</div>
+  </div>
+</div>
+```
+
+While this layout can work for some grid usage scenarios, we probably will want
+more control over how many columns our layout will span at each given
+breakpoint.
+
+By default, `@octaviaflow/grid` uses the breakpoints defined in `@octaviaflow/layout`.
+There are five breakpoints: `sm`, `md`, `lg`, `xlg`, and `max`. You can use each
+one in combination with a column to specify the number of columns to span at a
+given breakpoint. For example, we could rewrite the above example to be:
+
+```html
+<div class="cds--grid">
+  <div class="cds--row">
+    <div class="cds--col-sm-1">1/4</div>
+    <div class="cds--col-sm-1">1/4</div>
+    <div class="cds--col-sm-1">1/4</div>
+    <div class="cds--col-sm-1">1/4</div>
+  </div>
+</div>
+```
+
+The `.cds--col-sm-1` class names tells us that this `<div>` should only span one
+column at our `sm` breakpoint. By default, as we scale beyond the breakpoint the
+layout will still take up a percentage of the overall width.
+
+## 📚 Examples
+
+If you're looking for more examples on how to use `@octaviaflow/grid`, we have some
+examples that you can check out:
+
+- [css-grid](./examples/css-grid)
+
+## 🙌 Contributing
+
+We're always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you're interested, definitely
+check out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀
+
+## 📝 License
+
+Licensed under the [Apache 2.0 License](/LICENSE).
+
+## <picture><source height="20" width="20" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-dark.svg"><source height="20" width="20" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"><img height="20" width="20" alt="IBM Telemetry" src="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"></picture> IBM Telemetry
+
+This package uses IBM Telemetry to collect de-identified and anonymized metrics
+data. By installing this package as a dependency you are agreeing to telemetry
+collection. To opt out, see
+[Opting out of IBM Telemetry data collection](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection).
+For more information on the data being collected, please see the
+[IBM Telemetry documentation](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics).

package/index.scss

@@ -0,0 +1,11 @@
+//
+// Copyright OctaviaFlow. 2025
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@forward 'scss/config';
+@forward 'scss/breakpoint';
+@forward 'scss/css-grid';
+@forward 'scss/flex-grid';

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@octaviaflow/grid",
+  "description": "Grid for digital and software products using the OctaviaFlow Design System",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octaviaflow-design-system.git",
+    "directory": "packages/grid"
+  },
+  "bugs": "https://github.com/octaviaflow-design-system/issues",
+  "files": [
+    "css",
+    "scss",
+    "index.scss",
+    "telemetry.yml"
+  ],
+  "keywords": [
+    "octaviaflow",
+    "octaviaflow-design-system",
+    "grid",
+    "react",
+    "components",
+    "react"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun run clean && octaviaflow-cli inline && octaviaflow-cli check \"scss/*.scss\"",
+    "clean": "rimraf scss/_inlined scss/vendor"
+  },
+  "dependencies": {
+    "@octaviaflow/layout": "^1.0.0"
+  },
+  "devDependencies": {
+    "@octaviaflow/cli": "^1.0.0",
+    "rimraf": "^6.0.0"
+  },
+  "eyeglass": {
+    "exports": false,
+    "name": "@octaviaflow/grid",
+    "sassDir": "scss",
+    "needs": "^1.3.0"
+  }
+}

package/scss/_breakpoint.scss

@@ -0,0 +1,222 @@
+//
+// Copyright OctaviaFlow. 2025
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use '@octaviaflow/layout/scss/convert';
+@use 'config' as *;
+
+/// Provide a map and index, and get back the relevant key value
+/// @access public
+/// @param {Map} $map - Map
+/// @param {Integer} $index - Key chain
+/// @return {String} Desired value
+/// @group @octaviaflow/layout
+@function -key-by-index($map, $index) {
+  $keys: map.keys($map);
+  @return list.nth($keys, $index);
+}
+
+/// Get the value of the next breakpoint, or null for the last breakpoint
+/// @param {String} $name - The name of the breakpoint
+/// @param {Map} $breakpoints [$grid-breakpoints] - A map of breakpoints where the key is the name of the breakpoint and the value is the values for the breakpoint
+/// @param {List} $breakpoint-names [map-keys($breakpoints)] - A list of names from the `$breakpoints` map
+/// @return {String}
+/// @access public
+/// @group @octaviaflow/layout
+@function breakpoint-next(
+  $name,
+  $breakpoints: $grid-breakpoints,
+  $breakpoint-names: map.keys($breakpoints)
+) {
+  $n: list.index($breakpoint-names, $name);
+  @if $n != null and $n < list.length($breakpoint-names) {
+    @return list.nth($breakpoint-names, $n + 1);
+  }
+  @return null;
+}
+
+/// Get the value of the previous breakpoint, or null for the first breakpoint
+/// @param {String} $name - The name of the breakpoint
+/// @param {Map} $breakpoints [$grid-breakpoints] - A map of breakpoints where the key is the name of the breakpoint and the value is the values for the breakpoint
+/// @param {List} $breakpoint-names [map-keys($breakpoints)] - A list of names from the `$breakpoints` map
+/// @return {String}
+/// @access public
+/// @group @octaviaflow/layout
+@function breakpoint-prev(
+  $name,
+  $breakpoints: $grid-breakpoints,
+  $breakpoint-names: map.keys($breakpoints)
+) {
+  $n: list.index($breakpoint-names, $name);
+  @if $n != null and $n > 1 {
+    @return list.nth($breakpoint-names, $n - 1);
+  }
+  @return null;
+}
+
+/// Check to see if the given breakpoint name
+/// @param {String} $name - The name of the breakpoint
+/// @param {Map} $breakpoints [$grid-breakpoints] - A map of breakpoints where the key is the name of the breakpoint and the value is the values for the breakpoint
+/// @return {Bool}
+/// @access public
+/// @group @octaviaflow/layout
+@function is-smallest-breakpoint($name, $breakpoints: $grid-breakpoints) {
+  @return list.index(map.keys($breakpoints), $name) == 1;
+}
+
+/// Returns the largest breakpoint name
+/// @param {Map} $breakpoints [$grid-breakpoints] - A map of breakpoints where the key is the name
+/// @return {String}
+/// @access public
+/// @group @octaviaflow/layout
+@function largest-breakpoint-name($breakpoints: $grid-breakpoints) {
+  $total-breakpoints: list.length($breakpoints);
+  @return -key-by-index($breakpoints, $total-breakpoints);
+}
+
+/// Get the infix for a given breakpoint in a list of breakpoints. Useful for generating the size part in a selector, for example: `.prefix--col-sm-2`.
+/// @param {String} $name - The name of the breakpoint
+/// @return {String}
+/// @access public
+/// @group @octaviaflow/layout
+@function breakpoint-infix($name) {
+  @return '-#{$name}';
+}
+
+/// Generate a media query from the width of the given breakpoint to infinity
+/// @param {String | Number} $name
+/// @param {Map} $breakpoints [$grid-breakpoints] - A map of breakpoints where the key is the name
+/// @content
+/// @access public
+/// @group @octaviaflow/layout
+@mixin breakpoint-up($name, $breakpoints: $grid-breakpoints) {
+  @if meta.type-of($name) == 'number' {
+    @media (min-width: $name) {
+      @content;
+    }
+  } @else if map.has-key($breakpoints, $name) {
+    $breakpoint: map.get($breakpoints, $name);
+    $width: map.get($breakpoint, width);
+    @if is-smallest-breakpoint($name, $breakpoints) {
+      @content;
+    } @else {
+      @media (min-width: $width) {
+        @content;
+      }
+    }
+  } @else {
+    @error 'Unable to find a breakpoint with name `#{$name}`. Expected one of: (#{map.keys($breakpoints)})';
+  }
+}
+
+/// Generate a media query for the maximum width of the given styles
+/// @param {String | Number} $name
+/// @param {Map} $breakpoints [$grid-breakpoints] - A map of breakpoints where the key is the name
+/// @content
+/// @access public
+/// @group @octaviaflow/layout
+@mixin breakpoint-down($name, $breakpoints: $grid-breakpoints) {
+  @if meta.type-of($name) == 'number' {
+    @media (max-width: $name) {
+      @content;
+    }
+  } @else if map.has-key($breakpoints, $name) {
+    // We borrow this logic from bootstrap for specifying the value of the
+    // max-width. The maximum width is calculated by finding the breakpoint and
+    // subtracting .02 from its value. This value is used instead of .01 to
+    // avoid rounding issues in Safari
+    // https://github.com/twbs/bootstrap/blob/c5b1919deaf5393fcca9e9b9d7ce9c338160d99d/scss/mixins/_breakpoints.scss#L34-L46
+    $breakpoint: map.get($breakpoints, $name);
+    $width: map.get($breakpoint, width) - 0.02;
+    @media (max-width: $width) {
+      @content;
+    }
+  } @else {
+    @error 'Unable to find a breakpoint with name `#{$name}`. Expected one of: (#{map.keys($breakpoints)})';
+  }
+}
+
+/// Generate a media query for the range between the lower and upper breakpoints
+/// @param {String | Number} $lower
+/// @param {String | Number} $upper
+/// @param {Map} $breakpoints [$grid-breakpoints] - A map of breakpoints where the key is the name
+/// @content
+/// @access public
+/// @group @octaviaflow/layout
+@mixin breakpoint-between($lower, $upper, $breakpoints: $grid-breakpoints) {
+  $is-number-lower: meta.type-of($lower) == 'number';
+  $is-number-upper: meta.type-of($upper) == 'number';
+  $min: null;
+  $max: null;
+  
+  @if $is-number-lower {
+    $min: $lower;
+  } @else {
+    $min: map.get($breakpoints, $lower);
+  }
+  
+  @if $is-number-upper {
+    $max: $upper;
+  } @else {
+    $max: map.get($breakpoints, $upper);
+  }
+
+  @if $min and $max {
+    $min-width: null;
+    $max-width: null;
+    
+    @if not $is-number-lower and $min {
+      $min-width: map.get($min, width);
+    } @else {
+      $min-width: $min;
+    }
+    
+    @if not $is-number-upper and $max {
+      $max-width: map.get($max, width);
+    } @else {
+      $max-width: $max;
+    }
+    @media (min-width: $min-width) and (max-width: $max-width) {
+      @content;
+    }
+  } @else if $min != null and $max == null {
+    @include breakpoint-up($lower) {
+      @content;
+    }
+  } @else if $min == null and $max != null {
+    @include breakpoint-down($upper) {
+      @content;
+    }
+  } @else {
+    @error 'Unable to find a breakpoint to satisfy: (#{$lower},#{$upper}). Expected both to be one of (#{map.keys($breakpoints)}).';
+  }
+}
+
+/// Generate media query for the largest breakpoint
+/// @param {Map} $breakpoints [$grid-breakpoints] - A map of breakpoints where the key is the name
+/// @content
+/// @access public
+/// @group @octaviaflow/layout
+@mixin largest-breakpoint($breakpoints: $grid-breakpoints) {
+  @include breakpoint(largest-breakpoint-name()) {
+    @content;
+  }
+}
+
+/// Generate a media query for a given breakpoint
+/// @param {String | Number} $name
+/// @param {Map} $breakpoints [$grid-breakpoints] - A map of breakpoints where the key is the name
+/// @content
+/// @access public
+/// @group @octaviaflow/layout
+@mixin breakpoint($name, $breakpoints: $grid-breakpoints) {
+  @include breakpoint-up($name, $breakpoints) {
+    @content;
+  }
+}

package/scss/_config.scss

@@ -0,0 +1,94 @@
+//
+// Copyright OctaviaFlow. 2025
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@use 'sass:map';
+@use '@octaviaflow/layout/scss/convert';
+
+/// Namespace prefix
+/// @type String
+/// @access public
+/// @group @octaviaflow/grid
+$prefix: 'cds' !default;
+
+/// Total columns used in the flex grid
+/// @type Number
+/// @access public
+/// @group @octaviaflow/grid
+$flex-grid-columns: 16 !default;
+
+/// Carbon gutter size in rem
+/// @type Number
+/// @access public
+/// @group @octaviaflow/layout
+$grid-gutter: convert.to-rem(32px) !default;
+
+/// Carbon condensed gutter size in rem
+/// @type Number
+/// @access public
+/// @group @octaviaflow/layout
+$grid-gutter-condensed: convert.to-rem(1px) !default;
+
+// Initial map of our breakpoints and their values
+/// @type Map
+/// @access public
+/// @group @octaviaflow/layout
+$grid-breakpoints: (
+  sm: (
+    columns: 4,
+    margin: 0,
+    width: convert.to-rem(320px),
+  ),
+  md: (
+    columns: 8,
+    margin: convert.to-rem(16px),
+    width: convert.to-rem(672px),
+  ),
+  lg: (
+    columns: 16,
+    margin: convert.to-rem(16px),
+    width: convert.to-rem(1056px),
+  ),
+  xlg: (
+    columns: 16,
+    margin: convert.to-rem(16px),
+    width: convert.to-rem(1312px),
+  ),
+  max: (
+    columns: 16,
+    margin: convert.to-rem(24px),
+    width: convert.to-rem(1584px),
+  ),
+) !default;
+
+@if $flex-grid-columns == 12 {
+  $grid-breakpoints: map.merge(
+    $grid-breakpoints,
+    (
+      lg:
+        map.merge(
+          map.get($grid-breakpoints, lg),
+          (
+            columns: 12,
+          )
+        ),
+      xlg:
+        map.merge(
+          map.get($grid-breakpoints, xlg),
+          (
+            columns: 12,
+          )
+        ),
+      max:
+        map.merge(
+          map.get($grid-breakpoints, max),
+          (
+            columns: 12,
+          )
+        ),
+    )
+  );
+}