Skip to content

Commit 4b7134c

Browse files
ZmyslnyZmyslny
committed
feat: 2 states readme EN
1 parent cdc9062 commit 4b7134c

File tree

3 files changed

+71
-63
lines changed

3 files changed

+71
-63
lines changed

‎assets/2-states-hero-icons.gif‎

22.9 KB
Loading

‎scripts/ColorSchemeSwitchThreeStates/README.md‎

Whitespace-only changes.

‎scripts/ColorSchemeSwitchTwoStates/README.md‎

Lines changed: 71 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,47 @@
11
# Color Scheme Switch - Two States (Light/Dark)
22

3-
Skrypt do przełączania między dwoma motywami kolorystycznymi: jasnym (light) i ciemnym (dark).
3+
A script for switching between two color schemes: light and dark.
44

5-
## Co robi ten skrypt?
5+
> **Icons used** (from [HeroIcons](https://heroicons.com)):
6+
>
7+
> ![View](/../assets/2-states-hero-icons.gif)
68
7-
Skrypt zapewnia funkcjonalność przełączania między jasnym i ciemnym motywem na stronie internetowej, z zachowaniem preferencji użytkownika w `localStorage`. Składa się z dwóch części:
9+
## What does this script do?
810

9-
### 1. InitScript - Inicjalizacja motywu przy ładowaniu strony
11+
The script provides functionality for switching between light and dark themes on a website, while preserving user preferences in `localStorage`. It consists of three parts:
1012

11-
**Plik:** `init-script.js`
13+
### 1. InitScript - Theme initialization on page load
1214

13-
Skrypt uruchamia się **przed wyrenderowaniem strony** (inline w `<head>`), aby uniknąć efektu **FOUC** (Flash of Unstyled Content).
15+
**File:** `init-script.js`
1416

15-
**Działanie:**
16-
- Sprawdza `localStorage.colorScheme` i jeśli użytkownik wcześniej wybrał motyw, go stosuje
17-
- Jeśli brak zapisanej preferencji, sprawdza systemowe ustawienia (`prefers-color-scheme`)
18-
- Dodaje klasę `dark` do `document.documentElement` gdy motyw ciemny jest aktywny
17+
The script runs **before the page renders** (inline in `<head>`) to avoid **FOUC** (Flash of Unstyled Content).
1918

20-
### 2. SwitchScript - Przełączanie motywu
19+
**Behavior:**
20+
- Checks `localStorage.colorScheme` and if the user has previously selected a theme, applies it
21+
- If there's no saved preference, checks system settings (`prefers-color-scheme`)
22+
- Adds the `dark` class to `document.documentElement` when dark theme is active
2123

22-
**Plik:** `switch-script.js`
24+
### 2. SwitchScript - Theme switching
2325

24-
Skrypt umożliwia przełączanie między motywami poprzez skrót klawiszowy (domyślnie klawisz `d`).
26+
**File:** `switch-script.js`
2527

26-
**Działanie:**
27-
- Udostępnia funkcję `window.inlineScripts.switchColorScheme()` do programowego przełączania motywu
28-
- Nasłuchuje skrótu klawiszowego (domyślnie `d`) i przełącza motyw
29-
- Zapisuje wybraną preferencję w `localStorage`
30-
- Inteligentnie ignoruje naciśnięcia klawisza gdy fokus jest na polach input, textarea, select lub elementach z contentEditable
28+
The script enables switching between themes via keyboard shortcut (default key `d`).
3129

32-
## Użycie
30+
**Behavior:**
31+
- Exposes the `window.inlineScripts.switchColorScheme()` function for programmatic theme switching
32+
- Listens for keyboard shortcut (default `d`) and switches the theme
33+
- Saves the selected preference in `localStorage`
34+
- Intelligently ignores key presses when focus is on input, textarea, select fields or elements with contentEditable
3335

34-
### Metoda 1: Przy użyciu klas PHP (zalecane)
36+
### 3. View with color scheme icons
3537

36-
**Krok 1:** Dodaj do swojego `AppServiceProvider`:
38+
A Blade view with light/dark theme icons that call the `window.inlineScripts.switchColorScheme()` function when clicked.
39+
40+
## Usage
41+
42+
### Method 1: Using PHP classes
43+
44+
**Step 1:** Add to your `AppServiceProvider`:
3745

3846
```php
3947
use Zmyslny\LaravelInlineScripts\Ready\ColorSchemeSwitchTwoStates\InitScript;
@@ -44,14 +52,14 @@ class AppServiceProvider extends ServiceProvider
4452
public function boot(): void
4553
{
4654
BladeInlineScripts::take(
47-
new InitScript(), // inicjalizuje motyw przy ładowaniu strony
48-
new SwitchScript('d') // przełącza motyw po naciśnięciu klawisza 'd'
55+
new InitScript(), // initializes the theme on page load
56+
new SwitchScript('d') // switches the theme when 'd' key is pressed
4957
)->registerAs('colorSchemeScripts');
5058
}
5159
}
5260
```
5361

54-
**Krok 2:** Wstaw dyrektywę Blade w swoim szablonie:
62+
**Step 2:** Insert the Blade directive in your template:
5563

5664
```blade
5765
<html>
@@ -63,27 +71,27 @@ class AppServiceProvider extends ServiceProvider
6371
...
6472
```
6573

66-
**Krok 3 (opcjonalnie):** Dodaj widok z ikonami motywów:
74+
**Step 3:** Add the view with theme icons:
6775

6876
```bash
6977
php artisan vendor:publish --tag=color-scheme-2-states-views
7078
```
7179

72-
Wybierz odpowiedni widok i wstaw go w swoim szablonie:
80+
Select the appropriate view and insert it in your template:
7381
- Blade + TailwindCss + Hero icons: `../views/color-scheme-switch-two-states/hero-icons-tailwind.blade.php`
7482
- Livewire/Alpine + TailwindCss + Hero icons: `../views/color-scheme-switch-two-states/hero-icons-tailwind-alpine.blade.php`
7583

76-
### Metoda 2: Bezpośrednie użycie plików JS
84+
### Method 2: Direct JS file usage
7785

78-
**Krok 1:** Opublikuj wbudowane skrypty:
86+
**Step 1:** Publish the built-in scripts:
7987

8088
```bash
8189
php artisan vendor:publish --tag=color-scheme-2-states-js
8290
```
8391

84-
Skopiuje to skrypty do `resources/js/color-scheme-switch-two-states/[init-script.js, switch-script.js]`.
92+
This will copy the scripts to `resources/js/color-scheme-switch-two-states/[init-script.js, switch-script.js]`.
8593

86-
**Krok 2:** Zarejestruj skrypty w `AppServiceProvider`:
94+
**Step 2:** Register the scripts in `AppServiceProvider`:
8795

8896
```php
8997
class AppServiceProvider extends ServiceProvider
@@ -93,7 +101,7 @@ class AppServiceProvider extends ServiceProvider
93101
BladeInlineScripts::takeFiles(
94102
[
95103
resource_path('js/color-scheme-switch-two-states/init-script.js'),
96-
['__DARK__' => 'dark'], // zmienne do zastąpienia w skrypcie
104+
['__DARK__' => 'dark'], // variables to replace in the script
97105
],
98106
[
99107
resource_path('js/color-scheme-switch-two-states/switch-script.js'),
@@ -104,23 +112,23 @@ class AppServiceProvider extends ServiceProvider
104112
}
105113
```
106114

107-
**Krok 3:** Wstaw dyrektywę Blade w swoim szablonie (tak samo jak w Metodzie 1).
115+
**Step 3:** Insert the Blade directive in your template (same as in Method 1).
108116

109-
## Konfiguracja
117+
## Configuration
110118

111-
### Zmiana klawisza przełączania
119+
### Changing the toggle key
112120

113-
Domyślnie skrypt używa klawisza `d` do przełączania motywów. Możesz to zmienić przekazując inny klawisz do konstruktora `SwitchScript`:
121+
By default, the script uses the `d` key to switch themes. You can change this by passing a different key to the `SwitchScript` constructor:
114122

115123
```php
116-
new SwitchScript('t') // użyj klawisza 't' zamiast 'd'
124+
new SwitchScript('t') // use 't' key instead of 'd'
117125
```
118126

119-
**Wymagania:** Klawisz musi być pojedynczą małą literą (a-z).
127+
**Requirements:** The key must be a single lowercase letter (a-z).
120128

121-
### Zmiana nazw klas CSS
129+
### Changing CSS class names
122130

123-
Domyślnie skrypt dodaje klasę `dark` do elementu `<html>`. Możesz to zmienić edytując wartości w enumie `SchemeTypeEnum`:
131+
By default, the script adds the `dark` class to the `<html>` element. You can change this by editing the values in the `SchemeTypeEnum` enum:
124132

125133
```php
126134
enum SchemeTypeEnum: string
@@ -130,66 +138,66 @@ enum SchemeTypeEnum: string
130138
}
131139
```
132140

133-
Lub przy użyciu bezpośrednich plików JS, zmieniając placeholdery:
141+
Or when using direct JS files, by changing the placeholders:
134142

135143
```php
136144
['__DARK__' => 'dark-mode', '__LIGHT__' => 'light-mode']
137145
```
138146

139-
## Programowe przełączanie motywu
147+
## Programmatic theme switching
140148

141-
Skrypt udostępnia funkcję do programowego przełączania motywu:
149+
The script exposes a function for programmatic theme switching:
142150

143151
```javascript
144152
window.inlineScripts.switchColorScheme();
145153
```
146154

147-
Możesz jej użyć np. w obsłudze kliknięcia przycisku:
155+
You can use it, for example, in a button click handler:
148156

149157
```html
150158
<button onclick="window.inlineScripts.switchColorScheme()">
151-
Przełącz motyw
159+
Toggle theme
152160
</button>
153161
```
154162

155-
## Struktura plików
163+
## File structure
156164

157165
```
158166
ColorSchemeSwitchTwoStates/
159-
├── InitScript.php # Klasa PHP do inicjalizacji motywu
160-
├── SwitchScript.php # Klasa PHP do przełączania motywu
161-
├── SchemeTypeEnum.php # Enum z wartościami motywów (dark/light)
167+
├── InitScript.php # PHP class for theme initialization
168+
├── SwitchScript.php # PHP class for theme switching
169+
├── SchemeTypeEnum.php # Enum with theme values (dark/light)
162170
├── js/
163-
│ ├── init-script.js # Skrypt inicjalizacji (inline w <head>)
164-
│ └── switch-script.js # Skrypt przełączania (inline w <head>)
171+
│ ├── init-script.js # Initialization script (inline in <head>)
172+
│ └── switch-script.js # Switching script (inline in <head>)
165173
└── view/
166-
├── hero-icons-tailwind.blade.php # Widok z ikonami (Blade + Tailwind)
167-
└── hero-icons-tailwind-alpine.blade.php # Widok z ikonami (Alpine + Tailwind)
174+
├── hero-icons-tailwind.blade.php # View with icons (Blade + Tailwind)
175+
└── hero-icons-tailwind-alpine.blade.php # View with icons (Alpine + Tailwind)
168176
```
169177

170-
## Jak to działa?
178+
## How does it work?
171179

172-
1. **Przy ładowaniu strony:** `init-script.js` sprawdza zapisaną preferencję lub preferencje systemowe i natychmiast aplikuje odpowiedni motyw
173-
2. **Przełączanie:** Po naciśnięciu skrótu klawiszowego, `switch-script.js` przełącza klasę `dark` i zapisuje wybór w `localStorage`
174-
3. **Następne wizyty:** Przy kolejnym ładowaniu strony, `init-script.js` odczyta zapisaną preferencję i zastosuje ją przed wyrenderowaniem strony
180+
1. **On page load:** `init-script.js` checks the saved preference or system preferences and immediately applies the appropriate theme
181+
2. **Switching:** After pressing the keyboard shortcut or clicking the icons, `switch-script.js` toggles the `dark` class and saves the choice in `localStorage`
182+
3. **Subsequent visits:** On the next page load, `init-script.js` will read the saved preference and apply it before the page renders
175183

176-
## Testowanie
184+
## Testing
177185

178-
Możesz opublikować testy jednostkowe dla skryptów JS:
186+
You can publish unit tests for the JS scripts:
179187

180188
```bash
181189
php artisan vendor:publish --tag=color-scheme-2-states-js-tests
182190
```
183191

184-
Lub opublikować wszystko naraz (skrypty JS, testy i widoki):
192+
Or publish everything at once (JS scripts, tests, and views):
185193

186194
```bash
187195
php artisan vendor:publish --tag=color-scheme-2-states-all
188196
```
189197

190-
## Różnica między Two States a Three States
198+
## Difference between Two States and Three States
191199

192-
- **Two States:** Przełączanie między jasnym i ciemnym motywem (2 stany)
193-
- **Three States:** Przełączanie między jasnym, ciemnym i systemowym motywem (3 stany)
200+
- **Two States:** Switching between light and dark theme (2 states)
201+
- **Three States:** Switching between light, dark, and system theme (3 states)
194202

195-
Jeśli potrzebujesz opcji "auto/system", użyj wariantu Three States.
203+
If you need an "auto/system" option, use the Three States variant.

0 commit comments

Comments
 (0)