feat: more built in safe area utilities

[Brentlok]

closes #246

Summary by CodeRabbit

Release Notes

• New Features
  • Added safe-area layout utilities with variants for individual sides (top, bottom, left, right), combined axes (x, y), and offset configurations to better handle edge padding in responsive designs.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes expand the safe-area insets system by introducing comprehensive directional CSS utilities (top-safe, bottom-safe, left-safe, right-safe and variants for safe-or-* and safe-offset-*), refactoring the underlying TypeScript generation logic to support these multiple safe-area modes, and adding test coverage for the new inset-safe-offset functionality.

Changes

Cohort / File(s)	Summary
Safe-Area TypeScript Generation packages/uniwind/src/css/insets.ts	Refactored insets system to support margin, padding, and inset types with multiple safe-area behaviors (safe, safe-or-, safe-offset-). Reworked internal helpers: getInsetsForSide (returns typed array of insets), getUtilityName (computes class name), getStyleProperty (derives CSS property), getStylesForSafeAreaType (transforms styles based on safe-area mode). Generation flow now iterates types/sides to build base styles, then per-utility blocks using helper-driven transformations.
CSS Utilities Export packages/uniwind/uniwind.css	Added 21 new public CSS utilities spanning directional safe-area insets: inset-safe*, x-safe*, y-safe*, and directional variants (top-safe*, bottom-safe*, left-safe*, right-safe*). Each variant supports three modes: base safe-area values, max() fallback for unsupported browsers (-or-*), and offset calculations (-offset-*).
Test Coverage packages/uniwind/tests/styles-parsing/safe-area.test.tsx	Added test case for inset-safe-offset-[10px] with four assertions validating computed style values for top, bottom, left, and right properties.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Safe areas now shine in four-fold grace,
Top, bottom, left, right—a rabbit's place!
With offsets and fallbacks, we hop with care,
CSS utilities blooming everywhere. ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat: more built in safe area utilities' directly summarizes the main change—expansion of safe-area utility classes to include directional variants.
Linked Issues check	✅ Passed	All coding requirements from issue #246 are met: top-safe, bottom-safe, left-safe, and right-safe utilities are now available alongside x-safe, y-safe, and their variants.
Out of Scope Changes check	✅ Passed	All changes align with issue #246 requirements; the refactored insets system and test additions directly support the expanded safe-area utility API.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

packages/uniwind/src/css/insets.ts (2)

57-83: String manipulation in getStylesForSafeAreaType is fragile.

The regex replacement assumes a specific format ": env(...)" and only replaces the first occurrence due to replace() without the g flag. This works correctly for single-property styles but could behave unexpectedly if the style format changes.

The use of replace(';', '') on line 63/72 also only removes the first semicolon, which is fine for single declarations but worth noting for future maintenance.

Overall, the logic is correct for the current use case.

---

93-99: Double blank lines between utilities.

Lines 97-98 add two empty strings, resulting in double blank lines between each utility block. This is likely intentional for readability in the generated CSS, but verify this matches the existing format in uniwind.css.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3743a91 and a0b8d4c.

📒 Files selected for processing (3)

• packages/uniwind/src/css/insets.ts
• packages/uniwind/tests/styles-parsing/safe-area.test.tsx
• packages/uniwind/uniwind.css

🔇 Additional comments (10)

packages/uniwind/src/css/insets.ts (4)

1-10: Clean type definitions.

The use of as const arrays with derived types ensures type safety and exhaustiveness checking. The Inset type correctly represents the four CSS inset directions.

---

17-37: Good exhaustiveness check with satisfies never.

The switch statement properly covers all Side cases and uses TypeScript's satisfies never pattern to ensure compile-time exhaustiveness. Returning an empty array in the default branch is a safe fallback.

---

39-47: Potential naming inconsistency for inset type with inset side.

When typeName === 'inset' and side === 'inset', the utility name becomes inset-safe (etc.), which is correct. However, when typeName !== 'inset' and side === 'inset', the sideSuffix becomes undefined due to 'inset'.at(0) returning 'i', not empty string as intended.

Wait, let me re-check: Line 44 checks side === 'inset' and sets sideSuffix = '', which is correct. The logic appears sound for generating names like m-safe, p-safe, mx-safe, mt-safe, etc.

---

85-102: Generation loop correctly produces all utility combinations.

The nested iteration over types, sides, and safeAreaTypes generates all required CSS utilities. The composition using getStylesForSafeAreaType properly transforms the base styles for each safe-area variant.

packages/uniwind/tests/styles-parsing/safe-area.test.tsx (2)

13-13: Good test coverage for the new inset-safe-offset-* utility.

The test validates that arbitrary length values ([10px]) work correctly with the new inset safe area offset utilities, covering all four directional properties.

---

23-26: No action needed. The test expectations are correct. The SAFE_AREA_INSET_LEFT and SAFE_AREA_INSET_RIGHT constants do not exist; the test setup explicitly configures left and right insets as 0 while using the SAFE_AREA_INSET_TOP and SAFE_AREA_INSET_BOTTOM constants for vertical insets. The asymmetry in the assertions reflects this intentional design.

Likely an incorrect or invalid review comment.

packages/uniwind/uniwind.css (4)

256-283: New inset-safe utilities correctly implement the requested feature.

The utilities properly set all four positioning properties (top, bottom, left, right) using env(safe-area-inset-*). The -or-* and -offset-* variants correctly use max() and calc() respectively, supporting both integer spacing and arbitrary length values.

This directly addresses issue #246's request for safe-area inset classNames.

---

285-321: Axis utilities (x-safe, y-safe) provide convenient shorthand.

These utilities complement the directional utilities by allowing developers to apply safe area insets to horizontal (left/right) or vertical (top/bottom) axes simultaneously.

---

323-377: Directional utilities (top-safe, bottom-safe, left-safe, right-safe) fulfill the issue request.

These utilities directly implement the classNames requested in issue #246, providing granular control over individual safe area inset directions with all three safe-area type variants.

---

379-380: Minor formatting change on dark variant.

The dark variant declaration now has a preceding blank line (line 378 is new). This is a minor formatting adjustment that improves visual separation.